openapi-directory/api/vtex.local/Master-Data-API-.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","servers":[{"url":"https://vtex.local"},{"description":"VTEX server url","url":"https://{accountName}.{environment}.com.br","variables":{"accountName":{"default":"{accountName}","description":"Name of the VTEX account. Used as part of the URL"},"environment":{"default":"{environment}","description":"Environment to use. Used as part of the URL."}}}],"info":{"contact":{},"description":"# ATTENTION: **This version isn't compliant with data entities of old version (e.g. CL and AD). It's possible to use this configuration only to new data entities.**\r\n\r\n\r\n## Welcome!\r\n\r\nVTEX Master Data is an easy-to-use, secure, fast, scalable and extensible repository. On it you can create your own Entities, store data and consult directly from the storefront or use it to store info for some external integration.\r\n\r\nThere are internal VTEX modules that use VTEX Master Data as data repository. We have the VTEX Customer Service, VTEX Profile System and VTEX InStore, for example. It is also used by other internal services.\r\n\r\nThere are two ways to use Master Data:\r\n\r\n1. Directly from the storefront\r\n2. External integration\r\n\r\n### Directly from the storefront\r\n\r\nIf your scenario is to be used inside the storefront, be aware of the following observations:\r\n\r\n1. Use the storefront host to query or store information to avoid **CORS**;\r\n2. Configure which information should be public and which shouldn't, inside the JSON Schema of the Data Entity;\r\n3. Do not create query loops (the storefront may be affected with Throttling and apis may be turned off as a security protection);\r\n4. Never add via JS any type of authentication key (x-vtex-api-appkey or x-vtex-api-apptoken);\r\n\r\n**It's important to avoid CORS using the relative path**\r\n\r\n### External Integration\r\n\r\nIf your scenario is to perform external integration, such as migrating client data from another service, be aware of the following observations:\r\n\r\n1. Use the host ```{{accountName}}.vtexcommercestable.com.br```;\r\n2. Use the authentication keys (x-vtex-api-appkey ou x-vtex-api-apptoken);\r\n\r\n### Most used attributes listed here\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| accountName | Account name in VTEX License Manager |\r\n| name | Data Entity name |\r\n| schema | JSON Schema of a Data Entity |\r\n| id | Identifier of a document |\r\n| x-vtex-api-appKey | User key |\r\n| x-vtex-api-appToken | User token |","title":"Master Data API - v2","version":"1.0","x-origin":[{"format":"openapi","url":"https://raw.githubusercontent.com/vtex/openapi-schemas/master/VTEX - Master Data API - v2.json","version":"3.0"}],"x-providerName":"vtex.local","x-serviceName":"Master-Data-API-"},"security":[{"appKey":[],"appToken":[]}],"tags":[{"description":"The APIs within this group are used to save documents and query them by id.\r\n\r\nIf the document has the id attribute or has fields that have been set to indexes with unique values, VTEX Master Data will attempt to identify the document. If the document is found a change will be made. If it is not found, an inclusion will be made. ** This scenario does not apply to the API with the POST verb**.\r\n\r\nOtherwise, a new document will always be created.\r\n\r\nYou can use the query string `_where` to apply an update only if the document is compliant with the clause.\r\n\r\nIn addition with this feature you can use the schema parameter `_schema` as a query string to apply the update only if the document is compliant with the schema. If the document is not compliant, the body of the response will have an array with each error, where the field ```Message``` indicates the type of the error.\r\n\r\n### Response status code\r\n\r\n1. Status Code 201: Document created successfully\r\n2. Status Code 200: Document changed successfully\r\n3. Status Code 304: There were no changes to the document\r\n4. Status Code 400: Invalid information in JSON\r\n5. Status Code 403: Unauthorized access\r\n","name":"Documents"},{"description":"The ```search``` API is intended to query a collection of documents.  ","name":"Search"},{"description":"The new `` scroll `` API has been developed to meet external integration scenarios. If you need to query the entire VTEX Master Data database, or your collection is over 10.000 documents, use this feature.","name":"Scroll"},{"name":"Schemas"},{"description":"Create alternative keys for data entities.","name":"Indices"},{"description":"Lets you know if a particular document is in one or more clusters.","name":"Clusters"},{"description":"Master Data documents are versioned. This means that for each change a new version is generated. The `versions` APIs allows to query the versions and also apply the state of a document to the most current version.","name":"Versions"},{"name":"Customer profiles"},{"name":"Addresses"}],"paths":{"/api/dataentities/Address/documents":{"post":{"deprecated":false,"description":"Creates new customer address. \r\n\r\n> You can use this request to create customer addresses according to any `AD` schema. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use [Master Data v2 schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).","operationId":"CreateNewCustomerAddress","parameters":[{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/_schema"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createUpdateAddressRequests"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Address/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"AD-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Create new customer address","tags":["Addresses"]}},"/api/dataentities/Address/documents/{id}":{"delete":{"deprecated":false,"description":"Deletes a customer address.","operationId":"DeleteCustomerAddress","parameters":[{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Address/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"AD-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Delete customer address","tags":["Addresses"]},"patch":{"deprecated":false,"description":"Partially updates a customer address.\r\n\r\n> You can use this request to update customer addresses according to any `AD` schema. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use [Master Data v2 schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).","operationId":"UpdateCustomerAddress","parameters":[{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createUpdateAddressRequests"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Address/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"AD-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Update customer address","tags":["Addresses"]}},"/api/dataentities/Client/documents":{"post":{"deprecated":false,"description":"Creates new customer profile.\r\n\r\n> You can use this request to create customer profiles according to any `CL` schema. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use [Master Data v2 schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).","operationId":"CreateNewCustomerProfilev2","parameters":[{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/_schema"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createUpdateProfileRequests"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Create new customer profile","tags":["Customer profiles"]}},"/api/dataentities/Client/documents/{id}":{"delete":{"deprecated":false,"description":"Deletes a customer profile.","operationId":"DeleteCustomerProfile","parameters":[{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Delete customer profile","tags":["Customer profiles"]},"patch":{"deprecated":false,"description":"Partially updates a customer profile.\r\n\r\n> You can use this request to update customer profiles according to any `CL` schema. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for the schemas you are using. Learn more about how to use [Master Data v2 schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).","operationId":"UpdateCustomerProfile","parameters":[{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createUpdateProfileRequests"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Update customer profile","tags":["Customer profiles"]}},"/api/dataentities/{dataEntityName}/documents":{"patch":{"deprecated":false,"description":"This request allows you to partially update a document corresponding to a given data entity.\r\n\r\n> You can use this request to create documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Example use cases\r\n\r\n### Client profile\r\n\r\nIn order to create a customer profile's `phone` and `isNewsletterOptIn` fields, choose the `CL` data entity and send a request similar to this:\r\n\r\nPATCH\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"phone\": \"+12025550195\",\r\n    \"isNewsletterOptIn\": false\r\n }\r\n```\r\n\r\n### Client address\r\n\r\nIn order to update the `receiverName` of an existing address, the data entity is `AD` and the request would look like this:\r\n\r\nPATCH\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"receiverName\": \"Lois Lane\"\r\n}\r\n```","operationId":"Createorupdatepartialdocument","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}},"description":"JSON with the fields to be updated.","required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Create partial document","tags":["Documents"]},"post":{"deprecated":false,"description":"This request allows you to create a new document corresponding to a given data entity. For example, you can create a new customer profile or address.\r\n\r\n> You can use this request to create documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to create.\r\n\r\n## Example use cases\r\n\r\n### Client profile\r\n\r\nIn order to create a new customer profile, choose the `CL` data entity and send a request similar to this:\r\n\r\nPOST\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"email\": \"clark.kent@examplemail.com\",\r\n    \"firstName\": \"Clark\",\r\n    \"lastName\": \"Kent\",\r\n    \"phone\": \"+12025550195\",\r\n    \"documentType\": \"CPF\",\r\n    \"document\": \"12345678900\"\r\n    \"isCorporate\": false,\r\n    \"isNewsletterOptIn\": false,\r\n    \"localeDefault\": \"en-US\"\r\n }\r\n```\r\n\r\n### Client address\r\n\r\nFor a new address, the data entity is `AD` and the request would look like this:\r\n\r\nPOST\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"addressName\": \"My House\",\r\n    \"addressType\": \"residential\",\r\n    \"city\": \"Metropolis\",\r\n    \"complement\": \"\",\r\n    \"country\": \"USA\",\r\n    \"postalCode\": \"11375\",\r\n    \"receiverName\": \"Clark Kent\",\r\n    \"reference\": null,\r\n    \"state\": \"MP\",\r\n    \"street\": \"Baker Street\",\r\n    \"neighborhood\": \"Upper east side\",\r\n    \"number\": \"21\",\r\n    \"userId\": \"7e03m794-a33a-11e9-84rt6-0adfa64s5a8e\"\r\n}\r\n```","operationId":"Createnewdocument","parameters":[{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/_schema"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Create new document","tags":["Documents"]}},"/api/dataentities/{dataEntityName}/documents/{id}":{"delete":{"deprecated":false,"description":"It allows to delete a document.","operationId":"Deletedocument","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"responses":{"200":{"description":"OK","headers":{}}},"summary":"Delete document","tags":["Documents"]},"get":{"deprecated":false,"description":"Gets document by ID.\n\r\n\r> Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.","operationId":"Getdocument","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"responses":{"200":{"content":{"application/json":{"example":{"accountId":"14af940d-9300-4279-9355-61d44c2ff879","accountName":"my-store-name","dataEntityId":"Client","id":"b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/Using_fields_all"}}},"description":"Sucessful response","headers":{}}},"summary":"Get document","tags":["Documents"]},"patch":{"deprecated":false,"description":"This request allows you to partially update a document corresponding to a given data entity. For example, you can update some fields of a customer profile or address.\r\n\r\n> You can use this request to update documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Example use cases\r\n\r\n### Client profile\r\n\r\nIn order to update a customer profile's `phone` and `isNewsletterOptIn` fields, choose the `CL` data entity and send a request similar to this:\r\n\r\nPATCH\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents/123456789abc\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"phone\": \"+12025550195\",\r\n    \"isNewsletterOptIn\": false\r\n }\r\n```\r\n\r\n### Client address\r\n\r\nIn order to update the `receiverName` of an existing address, the data entity is `AD` and the request would look like this:\r\n\r\nPATCH\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents/123456789abc\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"receiverName\": \"Lois Lane\"\r\n}\r\n```","operationId":"Updatepartialdocument","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/_where"},{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Update partial document","tags":["Documents"]},"put":{"deprecated":false,"description":"Update an existing document corresponding to a given data entity. For example, you can update a customer profile or address.\r\n\r\n> You can use this request to update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Example use cases\r\n\r\n### Client profile\r\n\r\nIn order to update an existing customer profile, choose the `CL` data entity and send a request similar to this:\r\n\r\nPUT\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents/123456789abc\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"email\": \"clark.kent@examplemail.com\",\r\n    \"firstName\": \"Clark\",\r\n    \"lastName\": \"Kent\",\r\n    \"phone\": \"+12025550195\",\r\n    \"documentType\": \"CPF\",\r\n    \"document\": \"12345678900\"\r\n    \"isCorporate\": false,\r\n    \"isNewsletterOptIn\": false,\r\n    \"localeDefault\": \"en-US\"\r\n }\r\n```\r\n\r\n### Client address\r\n\r\nTo update an address, the data entity is `AD` and the request would look like this:\r\n\r\nPUT\r\n```\r\nhttps://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents/123456789abc\r\n```\r\n\r\nRequest body\r\n```json\r\n{\r\n    \"addressName\": \"My House\",\r\n    \"addressType\": \"residential\",\r\n    \"city\": \"Metropolis\",\r\n    \"complement\": \"\",\r\n    \"country\": \"USA\",\r\n    \"postalCode\": \"11375\",\r\n    \"receiverName\": \"Clark Kent\",\r\n    \"reference\": null,\r\n    \"state\": \"MP\",\r\n    \"street\": \"Baker Street\",\r\n    \"neighborhood\": \"Upper east side\",\r\n    \"number\": \"21\",\r\n    \"userId\": \"7e03m794-a33a-11e9-84rt6-0adfa64s5a8e\"\r\n}\r\n```","operationId":"Updateentiredocument","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/_where"},{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Update entire document","tags":["Documents"]}},"/api/dataentities/{dataEntityName}/documents/{id}/clusters":{"post":{"deprecated":false,"description":"Check if a document is present in one or more clusters (specific set of field values).\r\n\r\n> There is a limit of five rules per request.","operationId":"Validatedocumentbyclusters","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"}],"requestBody":{"content":{"application/json":{"example":"[\n    {\n        \"name\": \"male\",        \n        \"rule\": \"gender=male\"\n    },\n    {\n        \"name\": \"complex\",\n        \"rule\": \"((gender=male AND percent=0.35) AND any is null) AND (name=*go*)\"\n    },    \n    {\n        \"name\": \"complex2\",\n        \"rule\": \"((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)\"\n    },\n    {\n        \"name\": \"createdIn\",\n        \"rule\": \"createdIn between 2015-10-28 AND 2015-10-30\"\n    }\n]","schema":{"default":"[\n    {\n        \"name\": \"male\",        \n        \"rule\": \"gender=male\"\n    },\n    {\n        \"name\": \"complex\",\n        \"rule\": \"((gender=male AND percent=0.35) AND any is null) AND (name=*go*)\"\n    },    \n    {\n        \"name\": \"complex2\",\n        \"rule\": \"((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)\"\n    },\n    {\n        \"name\": \"createdIn\",\n        \"rule\": \"createdIn between 2015-10-28 AND 2015-10-30\"\n    }\n]","format":"json","type":"string"}}},"description":"Request body for validating a document by clusters","required":true},"responses":{"200":{"description":"OK","headers":{}}},"summary":"Validate document by clusters","tags":["Clusters"]}},"/api/dataentities/{dataEntityName}/documents/{id}/versions":{"get":{"deprecated":false,"description":"Allows to list the versions of a document.","operationId":"Listversions","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"},{"description":"If true, return all the fields in each version of the document","in":"query","name":"load","required":false,"schema":{"default":true,"type":"boolean"}},{"description":"If `load` is true, the response will return only these specific fields","in":"query","name":"fields","required":false,"schema":{"default":"id,dataEntityId,isNewsletterOptIn,createdBy","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":[{"date":"2025-04-15T13:51:55.787Z","document":{"createdBy":"81fc8b10-25b7-48de-b425-7b93554002cc","dataEntityId":"Client","id":"72e7f8dd-1168-23ec-82ac-0e2b61663eb4","isNewsletterOptIn":true},"id":"_EAR0cJ7XB5k5grnmm0zeKGlVvVM9WCPy_"},{"date":"2025-04-15T13:51:55.787Z","document":{"createdBy":"81fc8b10-25b7-48de-b425-7b93554002cc","dataEntityId":"Client","id":"72e7f8dd-1168-23ec-82ac-0e2b61663eb4","isNewsletterOptIn":true},"id":"_E5SH9WXVvhPBNnbQtYAAGqrIysIeNYhV_"}],"schema":{"items":{"$ref":"#/components/schemas/Listversion"},"type":"array"}}},"description":"OK","headers":{}}},"summary":"List versions","tags":["Versions"]}},"/api/dataentities/{dataEntityName}/documents/{id}/versions/{versionId}":{"get":{"deprecated":false,"description":"Returns the version of a document.","operationId":"Getversion","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/versionId"}],"responses":{"200":{"content":{"application/json":{"example":{"author":"user-id","document":{"accountId":"my-account-id","accountName":"my-account","carttag":null,"checkouttag":null,"dataEntityId":"Client","departmentVisitedTag":{"DisplayValue":"Ar e Ventilação","Scores":{"Ar e Ventilação":[{"Date":"2025-04-15T13:51:55.787Z","Point":1,"Until":"2025-04-15T13:51:55.787Z"}]}},"email":"teste@mail.com","followers":[],"id":"my-id","rclastsession":"163054c0-954f-11e6-891e-4d2b1c3450a4","rclastsessiondate":"2025-04-15T13:51:55.787Z"},"id":"version-id"},"schema":{"$ref":"#/components/schemas/Getversion"}}},"description":"OK","headers":{}}},"summary":"Get version","tags":["Versions"]},"put":{"deprecated":false,"description":"Updates document with version values.","operationId":"Putversion","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/id"},{"description":"ID of the version to update","in":"path","name":"versionId","required":true,"schema":{"default":"{{versionId}}","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"example":{"Href":"http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e","Id":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e"},"schema":{"$ref":"#/components/schemas/documentResponse"}}},"description":"OK"}},"summary":"Put version","tags":["Versions"]}},"/api/dataentities/{dataEntityName}/indices":{"get":{"deprecated":false,"description":"Returns the list of indices by data entity.","operationId":"Getindices","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"}],"responses":{"200":{"description":"OK","headers":{}}},"summary":"Get indices","tags":["Indices"]},"put":{"deprecated":false,"description":"Create an index.","operationId":"Putindices","parameters":[{"$ref":"#/components/parameters/dataEntityName"}],"requestBody":{"content":{"application/json":{"example":{"fields":"fieldName","multiple":false,"name":"indexName"},"schema":{"$ref":"#/components/schemas/PutindicesRequest"}}},"description":"Request body for creating an index","required":true},"responses":{"200":{"description":"OK","headers":{}}},"summary":"Put indices","tags":["Indices"]}},"/api/dataentities/{dataEntityName}/indices/{index_name}":{"delete":{"deprecated":false,"description":"Delete an index.","operationId":"Deleteindexbyname","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/index_name"}],"responses":{"200":{"description":"OK","headers":{}}},"summary":"Delete index by name","tags":["Indices"]},"get":{"deprecated":false,"description":"Returns an index.","operationId":"Getindexbyname","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/index_name"}],"responses":{"200":{"description":"OK","headers":{}}},"summary":"Get index by name","tags":["Indices"]}},"/api/dataentities/{dataEntityName}/schemas":{"get":{"deprecated":false,"description":"Return the schemas saved.","operationId":"Getschemas","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"}],"responses":{"200":{"description":"OK","headers":{}}},"summary":"Get schemas","tags":["Schemas"]}},"/api/dataentities/{dataEntityName}/schemas/{schemaName}":{"delete":{"deprecated":false,"description":"Deletes an existing schema for a given data entity.","operationId":"Deleteschemabyname","parameters":[{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/schemaName"}],"responses":{"204":{"description":"No Content"}},"summary":"Delete schema by name","tags":["Schemas"]},"get":{"deprecated":false,"description":"Returns an existing schema for a given data entity.","operationId":"Getschemabyname","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/schemaName"}],"responses":{"200":{"description":"OK","headers":{}}},"summary":"Get schema by name","tags":["Schemas"]},"put":{"deprecated":false,"description":"Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle)\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).","operationId":"Saveschemabyname","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/schemaName"}],"requestBody":{"content":{"application/json":{"example":{"properties":{"name":{"type":"string"}}},"schema":{"$ref":"#/components/schemas/SaveschemabynameRequest"}}},"description":"Request body for saving schema","required":true},"responses":{"200":{"description":"OK","headers":{}}},"summary":"Save schema by name","tags":["Schemas"]}},"/api/dataentities/{dataEntityName}/scroll":{"get":{"deprecated":false,"description":"In the first request, the `X-VTEX-MD-TOKEN` token will be returned in the header. This token must be passed to the next request in the query string `_token` parameter. The token has a timeout of 10 minutes, which refreshes after each request.\r\n\r\nAfter the token is obtained it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\n\r\n\r> Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Request examples\r\n\r\nFirst request:\r\n```\r\n/dataentities/Client/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the next requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Client/scroll?_token={tokenValueExample}\r\n```","operationId":"Scrolldocuments","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/_token"},{"$ref":"#/components/parameters/REST-Range"},{"$ref":"#/components/parameters/_fields"},{"$ref":"#/components/parameters/_where"},{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/_keyword"},{"$ref":"#/components/parameters/_sort"}],"responses":{"200":{"description":"OK","headers":{}},"429":{"content":{"application/json":{"example":{},"schema":{"description":"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`."}}},"description":"Too Many Requests"}},"summary":"Scroll documents","tags":["Scroll"]}},"/api/dataentities/{dataEntityName}/search":{"get":{"deprecated":false,"description":"Retrieves documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned results from 0 to 100 of a total 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\r> Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n### Simple filter\r\n\r\n```\r\n/dataentities/Client/search?email=my@email.com\r\n```\r\n\r\n### Complex filter\r\n\r\n```\r\n/dataentities/Client/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)\r\n```\r\n\r\n### Date Range\r\n\r\n```\r\n/dataentities/Client/search?_where=createdIn between 2001-01-01 AND 2016-01-01\r\n```\r\n\r\n### Range numeric fields\r\n\r\n```\r\n/dataentities/Client/search?_where=age between 18 AND 25\r\n```\r\n\r\n### Partial filter\r\n\r\n```\r\n/dataentities/Client/search?firstName=*Maria*\r\n```\r\n\r\n### Filter for null values\r\n\r\n```\r\n/dataentities/Client/search?_where=firstName is null\r\n```\r\n\r\n### Filter for non-null values\r\n\r\n```\r\n/dataentities/Client/search?_where=firstName is not null\r\n```\r\n\r\n### Filter for difference\r\n```\r\n/dataentities/Client/search?_where=firstName<>maria\r\n```\r\n\r\n### Filter greater than or less than\r\n```\r\n/dataentities/Client/search?_where=number>5\r\n/dataentities/Client/search?_where=date<2001-01-01\r\n```","operationId":"Searchdocuments","parameters":[{"$ref":"#/components/parameters/dataEntityName"},{"$ref":"#/components/parameters/Content-Type"},{"$ref":"#/components/parameters/Accept"},{"$ref":"#/components/parameters/REST-Range"},{"$ref":"#/components/parameters/_fields"},{"$ref":"#/components/parameters/_where"},{"$ref":"#/components/parameters/_schema"},{"$ref":"#/components/parameters/_keyword"},{"$ref":"#/components/parameters/_sort"}],"responses":{"200":{"description":"OK"},"503":{"content":{"application/json":{"example":{},"schema":{"description":"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`."}}},"description":"Service Unavailable"}},"summary":"Search documents","tags":["Search"]}}},"components":{"parameters":{"Accept":{"description":"HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.","in":"header","name":"Accept","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},"Content-Type":{"description":"Type of the content being sent.","in":"header","name":"Content-Type","required":true,"schema":{"example":"application/json","type":"string"},"style":"simple"},"REST-Range":{"description":"Defines the collection of documents to be returned. A range within the collection limited by 100 documents per query.","in":"header","name":"REST-Range","required":true,"schema":{"example":"resources=0-10","type":"string"},"style":"simple"},"_fields":{"description":"Fields that should be returned by document. Separate fields' names with commas. For example `_fields=email,firstName,document`. You can also use `_all` to fetch all fields.","in":"query","name":"_fields","required":false,"schema":{"default":"email,firstName,document","type":"string"},"style":"form"},"_keyword":{"description":"String to search. Use quotes for a partial query. For example, `_keyword=Maria` or `_keyword=\"Maria\"`.","in":"query","name":"_keyword","required":false,"schema":{"example":"String to search","type":"string"},"style":"form"},"_schema":{"description":"Name of the schema the document to be created needs to be compliant with.","in":"query","name":"_schema","required":false,"schema":{"example":"schema","type":"string"},"style":"form"},"_size":{"description":"Inform the number of documents per request. Maximum value of `1000`.","in":"query","name":"_size","required":false,"schema":{"default":100,"type":"integer"},"style":"form"},"_sort":{"description":"Sets sorting mode in two parts. The first part is the name of the field you want to sort by. In the second part, use `ASC` for ascending or `DESC` for descending.","in":"query","name":"_sort","required":false,"schema":{"default":"firstName ASC","type":"string"},"style":"form"},"_token":{"description":"Value of the header `X-VTEX-MD-TOKEN` returned in your first request. Send its value in this query string in the subsequent requests. The token has a timeout of 10 minutes, which refreshes after each new request.","in":"query","name":"_token","required":false,"schema":{"default":"{tokenValueExample}","type":"string"},"style":"form"},"_where":{"description":"Filter specification.","in":"query","name":"_where","required":false,"schema":{"example":"firstName is not null.","type":"string"},"style":"form"},"dataEntityName":{"description":"Name of the data entity. Defined by the api. Examples of native data entities you can use are `CL` for client profiles and `AD` for client addresses.","in":"path","name":"dataEntityName","required":true,"schema":{"example":"Client","type":"string"}},"id":{"description":"ID of the Document.","in":"path","name":"id","required":true,"schema":{"example":"Client-b818cbda-e489-11e6-94f4-0ac138d2d42e","type":"string"},"style":"simple"},"index_name":{"description":"Name of the index.","in":"path","name":"index_name","required":true,"schema":{"example":"{{index_name}}","type":"string"},"style":"simple"},"schemaName":{"description":"Name of the schema.","in":"path","name":"schemaName","required":true,"schema":{"example":"{{schema}}","type":"string"},"style":"simple"},"versionId":{"description":"ID of the version to update.","in":"path","name":"versionId","required":true,"schema":{"default":"123456789abc","type":"string"},"style":"simple"}},"schemas":{"ArEVentilaO":{"example":{"Date":"2025-04-15T13:51:55.788Z","Point":1,"Until":"2025-04-15T13:51:55.788Z"},"properties":{"Date":{"type":"string"},"Point":{"format":"int32","type":"integer"},"Until":{"type":"string"}},"required":["Point","Date","Until"],"title":"ArEVentilaO","type":"object"},"DEPRECATED_DocumentRequest":{"description":"This can be any pure JSON document.","properties":{"field":{"description":"This can be any JSON document field.","type":"string"}},"type":"object"},"DepartmentVisitedTag":{"example":{"DisplayValue":"Ar e Ventilação","Scores":{"Ar e Ventilação":[{"Date":"2025-04-15T13:51:55.788Z","Point":1,"Until":"2025-04-15T13:51:55.788Z"}]}},"properties":{"DisplayValue":{"type":"string"},"Scores":{"$ref":"#/components/schemas/Scores"}},"required":["DisplayValue","Scores"],"title":"DepartmentVisitedTag","type":"object"},"Document":{"example":{"accountId":"my-account-id","accountName":"my-account","carttag":null,"checkouttag":null,"dataEntityId":"Client","departmentVisitedTag":{"DisplayValue":"Ar e Ventilação","Scores":{"Ar e Ventilação":[{"Date":"2025-04-15T13:51:55.788Z","Point":1,"Until":"2025-04-15T13:51:55.788Z"}]}},"email":"teste@mail.com","followers":[],"id":"my-id","rclastsession":"163054c0-954f-11e6-891e-4d2b1c3450a4","rclastsessiondate":"2025-04-15T13:51:55.788Z"},"properties":{"accountId":{"type":"string"},"accountName":{"type":"string"},"carttag":{"nullable":true,"type":"string"},"checkouttag":{"nullable":true,"type":"string"},"dataEntityId":{"type":"string"},"departmentVisitedTag":{"$ref":"#/components/schemas/DepartmentVisitedTag"},"email":{"type":"string"},"followers":{"description":"","items":{"type":"string"},"type":"array"},"id":{"type":"string"},"rclastsession":{"type":"string"},"rclastsessiondate":{"type":"string"}},"required":["id","dataEntityId","accountId","accountName","followers","email","rclastsession","rclastsessiondate","checkouttag","carttag","departmentVisitedTag"],"title":"Document","type":"object"},"DocumentRequest":{"additionalProperties":{"description":"JSON document fields.","type":"string"},"description":"This can be any pure JSON document. Add new _Key-Value_ pairs to test.","title":"DocumentRequest","type":"object"},"Getversion":{"example":{"author":"user-id","document":{"accountId":"my-account-id","accountName":"my-account","carttag":null,"checkouttag":null,"dataEntityId":"Client","departmentVisitedTag":{"DisplayValue":"Ar e Ventilação","Scores":{"Ar e Ventilação":[{"Date":"2025-04-15T13:51:55.788Z","Point":1,"Until":"2025-04-15T13:51:55.788Z"}]}},"email":"teste@mail.com","followers":[],"id":"my-id","rclastsession":"163054c0-954f-11e6-891e-4d2b1c3450a4","rclastsessiondate":"2025-04-15T13:51:55.788Z"},"id":"version-id"},"properties":{"author":{"type":"string"},"document":{"$ref":"#/components/schemas/Document"},"id":{"type":"string"}},"required":["id","author","document"],"title":"Getversion","type":"object"},"Listversion":{"properties":{"date":{"type":"string"},"document":{"type":"object"},"id":{"type":"string"}},"required":["id","date"],"title":"Listversion","type":"object"},"Name":{"example":{"type":"string"},"properties":{"type":{"type":"string"}},"required":["type"],"title":"Name","type":"object"},"Properties":{"example":{"name":{"type":"string"}},"properties":{"name":{"$ref":"#/components/schemas/Name"}},"required":["name"],"title":"Properties","type":"object"},"PutindicesRequest":{"example":{"fields":"fieldName","multiple":false,"name":"indexName"},"properties":{"fields":{"description":"Comma-separted fields of the index","type":"string"},"multiple":{"description":"Determines whether the values need to be unique. If false, values must be unique.","type":"boolean"},"name":{"description":"Name to identify the index","type":"string"}},"required":["name","multiple","fields"],"title":"PutindicesRequest","type":"object"},"SaveschemabynameRequest":{"example":{"properties":{"name":{"type":"string"}}},"properties":{"properties":{"$ref":"#/components/schemas/Properties"}},"required":["properties"],"title":"SaveschemabynameRequest","type":"object"},"Scores":{"example":{"Ar e Ventilação":[{"Date":"2025-04-15T13:51:55.788Z","Point":1,"Until":"2025-04-15T13:51:55.788Z"}]},"properties":{"Ar e Ventilação":{"description":"","items":{"$ref":"#/components/schemas/ArEVentilaO"},"type":"array"}},"required":["Ar e Ventilação"],"title":"Scores","type":"object"},"Using_fields_all":{"example":{"accountId":"14af940d-9300-4279-9355-61d44c2ff879","accountName":"my-store-name","dataEntityId":"Client","id":"b818cbda-e489-11e6-94f4-0ac138d2d42e"},"properties":{"accountId":{"type":"string"},"accountName":{"type":"string"},"dataEntityId":{"type":"string"},"id":{"type":"string"}},"required":["id","accountId","accountName","dataEntityId"],"title":"Using_fields=_all","type":"object"},"ValidatedocumentbyclustersRequest":{"example":{"name":"male","rule":"gender=male"},"properties":{"name":{"type":"string"},"rule":{"type":"string"}},"required":["name","rule"],"title":"ValidatedocumentbyclustersRequest","type":"object"},"createUpdateAddressRequests":{"properties":{"addressName":{"description":"Address name.","example":"My house","nullable":true,"type":"string"},"addressType":{"description":"Type of address. For example, `Residential` or `Pickup`, among others.","example":"residential","nullable":true,"type":"string"},"city":{"description":"City of the shipping address.","example":"Rio de Janeiro","nullable":true,"type":"string"},"complement":{"description":"Complement to the shipping address in case it applies.","example":"3rd floor","nullable":true,"type":"string"},"country":{"description":"Three letter ISO code of the country of the shipping address.","example":"BRA","nullable":true,"type":"string"},"neighborhood":{"description":"Neighborhood of the address.","example":"Botafogo","nullable":true,"type":"string"},"number":{"description":"Number of the building, house or apartment in the shipping address.","example":"300","nullable":true,"type":"string"},"postalCode":{"description":"Postal Code.","example":"12345-000","nullable":true,"type":"string"},"receiverName":{"description":"Name of the person who is going to receive the order.","example":"Clark Kent.","nullable":true,"type":"string"},"reference":{"description":"Complement that might help locate the shipping address more precisely in case of delivery.","example":"Grey building","nullable":true,"type":"string"},"state":{"description":"State of the shipping address.","example":"Rio de Janeiro","nullable":true,"type":"string"},"street":{"description":"Street of the address.","example":"Praia de Botafogo","nullable":true,"type":"string"},"userId":{"description":"ID of the customer to whom the address belongs.","example":"7e03m794-a33a-11e9-84rt6-0adfa64s5a8e","nullable":true,"type":"string"}},"type":"object"},"createUpdateProfileRequests":{"properties":{"document":{"description":"Client document.","example":"12345678900","nullable":true,"type":"string"},"documentType":{"description":"Client document type.","example":"CPF","nullable":true,"type":"string"},"email":{"description":"Client email address.","example":"clark.kent@examplemail.com","nullable":true,"type":"string"},"firstName":{"description":"Client first name.","example":"Clark","nullable":true,"type":"string"},"isCorporate":{"description":"Indicates whether client is corporate.","example":false,"nullable":true,"type":"boolean"},"isNewsletterOptIn":{"description":"Indicates whether client otped to receive the store newsletter.","example":false,"nullable":true,"type":"boolean"},"lastName":{"description":"Client last name.","example":"Kent","nullable":true,"type":"string"},"localeDefault":{"description":"Default locale, used to set store language and currency, for example.","example":"en-US","nullable":true,"type":"string"},"phone":{"description":"Client telephone number.","example":"+12025550195","nullable":true,"type":"string"}},"type":"object"},"documentResponse":{"properties":{"Href":{"description":"Document reference URL.","type":"string"},"Id":{"description":"ID of the document that was created or updated.","type":"string"}},"required":["Id","Href"],"type":"object"}},"securitySchemes":{"appKey":{"in":"header","name":"X-VTEX-API-AppKey","type":"apiKey"},"appToken":{"in":"header","name":"X-VTEX-API-AppToken","type":"apiKey"}}}}