{ "openapi": "3.0.0", "info": { "title": "Master Data API - v2", "description": "> This version is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n\r\nMaster Data is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integration)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n\r\n\r\n## External Integration\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host ```{{accountName}}.vtexcommercestable.com.br```.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\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` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Customer profiles\r\n\r\n- `POST` [Create new customer profile](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/Client/documents)\r\n- `PATCH` [Update customer profile](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/Client/documents/-id-)\r\n- `DELETE` [Delete customer profile](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/Client/documents/-id-)\r\n\r\n### Addresses\r\n\r\n- `POST` [Create new customer address](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/Address/documents)\r\n- `PATCH` [Update customer address](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/Address/documents/-id-)\r\n- `DELETE` [Delete customer address](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/Address/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "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": { "/api/dataentities/{dataEntityName}/documents": { "post": { "tags": [ "Documents" ], "summary": "Create new document", "description": "Creates a new document with an ID automatically generated by VTEX, 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> To create a document with a custom ID, refer to the [Create document with custom ID](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-) endpoint.\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 `Client` data entity and send a request similar to this:\r\n\r\n```\r\nPOST https://examplestore.vtexcommercestable.com.br/api/dataentities/Client/documents\r\n```\r\n\r\n**Request body example**\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 `Address` and the request would look like this:\r\n\r\n```\r\nPOST https://examplestore.vtexcommercestable.com.br/api/dataentities/Address/documents\r\n```\r\n\r\n**Request body example**\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```\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| inStore Sales Person | Full access to all documents |\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "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" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentResponse" }, "example": { "Id": "Client-cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "Href": "http://cosmetics2.vtexcommercestable.com.br/api/dataentities/Client/documents/cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "DocumentId": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827" } } } } }, "deprecated": false }, "patch": { "tags": [ "Documents" ], "summary": "Create partial document", "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 `Client` 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\n**Request body example**\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 `Address` 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\n**Request body example**\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": { "description": "JSON with the fields to be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "phone": "+12025550195", "isNewsletterOptIn": false } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/Client/documents": { "post": { "tags": [ "Customer profiles" ], "summary": "Create new customer profile", "description": "Creates new customer profile.\r\n\r\n> You can use this request to create customer profiles according to any `Client` 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": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/Client/documents/{id}": { "patch": { "tags": [ "Customer profiles" ], "summary": "Update customer profile", "description": "Partially updates a customer profile.\r\n\r\n> You can use this request to update customer profiles according to any `Client` 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": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false }, "delete": { "tags": [ "Customer profiles" ], "summary": "Delete customer profile", "description": "Deletes a customer profile.", "operationId": "DeleteCustomerProfile", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/Address/documents": { "post": { "tags": [ "Addresses" ], "summary": "Create new customer address", "description": "Creates new customer address. \r\n\r\n> You can use this request to create customer addresses according to any `Address` 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": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Address/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/Address/documents/{id}": { "patch": { "tags": [ "Addresses" ], "summary": "Update customer address", "description": "Partially updates a customer address.\r\n\r\n> You can use this request to update customer addresses according to any `Address` 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": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Address/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false }, "delete": { "tags": [ "Addresses" ], "summary": "Delete customer address", "description": "Deletes a customer address.", "operationId": "DeleteCustomerAddress", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Address/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Get document", "description": "Retrieves a 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`.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| inStore Sales Person | Full access to all documents |\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/_fields" } ], "responses": { "200": { "description": "Sucessful response", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Using_fields_all" }, "example": { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "my-store-name", "dataEntityId": "Client" } } } } }, "deprecated": false }, "put": { "tags": [ "Documents" ], "summary": "Create document with custom ID or Update entire document", "description": "Creates a new document with a custom ID, or updates an entire document if there is already a document with the informed ID. For example, you can update a customer profile or address.\r\n\r\n> You can use this request to create or 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 `Client` 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\n**Request body example**\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 `Address` 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\n**Request body example**\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" }, { "name": "id", "in": "path", "description": "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.", "required": true, "style": "simple", "schema": { "type": "string", "example": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" } } }, "required": true }, "responses": { "200": { "description": "OK. Document changed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "201": { "description": "Created. Document created successfully." }, "304": { "description": "Not Modified. There were no changes to the document." }, "400": { "description": "Bad Request. Invalid information in JSON." }, "403": { "description": "Forbidden. Unauthorized access." } }, "deprecated": false }, "patch": { "tags": [ "Documents" ], "summary": "Update partial document", "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 `Client` 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\n**Request body example**\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 `Address` 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\n**Request body example**\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" }, "example": { "phone": "+12025550195", "isNewsletterOptIn": false } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "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": {} } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/search": { "get": { "tags": [ "Search" ], "summary": "Search documents", "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", "content": { "application/json": { "schema": { "type": "array", "description": "List of documents that correspond to the result of the search.", "items": { "$ref": "#/components/schemas/Using_fields_all" } }, "example": [ { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "my-store-name", "dataEntityId": "Client" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message.", "example": "Field 'X' not found in schema" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message.", "example": "Cannot filter by private fields" } } } } } }, "503": { "description": "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`." } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/scroll": { "get": { "tags": [ "Scroll" ], "summary": "Scroll documents", "description": "If you need to query the entire VTEX Master Data database, or your collection is over 10.000 documents, use this endpoint.\r\n\r\nIn 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 using 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 following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Client/scroll?_token={tokenValue}\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", "content": { "application/json": { "schema": { "type": "array", "description": "List of documents that correspond to the result of the scroll.", "items": { "$ref": "#/components/schemas/Using_fields_all" } }, "example": [ { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "my-store-name", "dataEntityId": "Client" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message.", "example": "Operation not found for this token: 'X'" } } } } } }, "429": { "description": "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`." } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/schemas": { "get": { "tags": [ "Schemas" ], "summary": "Get schemas", "description": "Retrieves all existing [schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity.", "operationId": "Getschemas", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with existing schemas. In case there is only one existing schema, it will be an object instead, without the `name` property and the named `schema` object, following the same structure as the [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-?endpoint=get-/api/dataentities/-dataEntityName-/schemas/-schemaName-) endpoint response.", "items": { "$ref": "#/components/schemas/GetSchemasResponse" } } } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/schemas/{schemaName}": { "get": { "tags": [ "Schemas" ], "summary": "Get schema by name", "description": "Returns an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) 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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, "example": { "properties": { "name": { "type": "string" } } } } } } }, "deprecated": false }, "put": { "tags": [ "Schemas" ], "summary": "Save schema by name", "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).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.", "operationId": "Saveschemabyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/schemaName" } ], "requestBody": { "description": "Request body for saving schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, "example": { "properties": { "name": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Success message.", "example": "JSON Schema persisted successfully. Revalidation and indexing process running in background." } } } } } } }, "deprecated": false }, "delete": { "tags": [ "Schemas" ], "summary": "Delete schema by name", "description": "Deletes an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) 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" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/indices": { "get": { "tags": [ "Indices" ], "summary": "Get indices", "description": "Returns the list of [indices](https://developers.vtex.com/docs/guides/master-data-components#index) by data entity.", "operationId": "Getindices", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with information about indices.", "items": { "$ref": "#/components/schemas/Index" } }, "example": [ { "name": "fullName", "acronym": "Client", "isGlobal": false, "multiple": false, "fields": "firstName,lastName" } ] } } } }, "deprecated": false }, "put": { "tags": [ "Indices" ], "summary": "Create index", "description": "Creates an [index](https://developers.vtex.com/docs/guides/master-data-components#index).", "operationId": "Putindices", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" } ], "requestBody": { "description": "Request body for creating an index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutindicesRequest" }, "example": { "name": "indexName", "multiple": false, "fields": "fieldName" } } }, "required": true }, "responses": { "200": { "description": "OK" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/indices/{index_name}": { "get": { "tags": [ "Indices" ], "summary": "Get index by name", "description": "Retrieves an [index](https://developers.vtex.com/docs/guides/master-data-components#index).", "operationId": "Getindexbyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/index_name" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" }, "example": { "name": "fullName", "acronym": "Client", "isGlobal": false, "multiple": false, "fields": "firstName,lastName" } } } } }, "deprecated": false }, "delete": { "tags": [ "Indices" ], "summary": "Delete index by name", "description": "Deletes an [index](https://developers.vtex.com/docs/guides/master-data-components#index).", "operationId": "Deleteindexbyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/index_name" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/clusters": { "post": { "tags": [ "Clusters" ], "summary": "Validate document by clusters", "description": "Checks 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": { "description": "Request body for validating a document by clusters", "content": { "application/json": { "schema": { "type": "array", "description": "Cluster validation rule information.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Cluster name." }, "rule": { "type": "string", "description": "Cluster validation rule." } } } }, "example": [ { "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" } ] } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with objects validating each cluster rule.", "items": { "type": "object", "description": "Cluster rule validation object.", "properties": { "name": { "type": "string", "description": "Cluster name." }, "isValid": { "type": "boolean", "description": "Informs if the document is valid according to the cluster rule (`true`) or not (`false`)." } } } }, "example": [ { "name": "male", "isValid": false }, { "name": "complex", "isValid": false }, { "name": "complex2", "isValid": false }, { "name": "createdIn", "isValid": false } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/versions": { "get": { "tags": [ "Versions" ], "summary": "List versions", "description": "Lists the versions of a document. \r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated.", "operationId": "Listversions", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "name": "load", "in": "query", "description": "If true, return all the fields in each version of the document.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "fields", "in": "query", "description": "If `load` is true, the response will return only these specific fields.", "required": false, "schema": { "type": "string", "default": "id,dataEntityId,isNewsletterOptIn,createdBy" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listversion" } }, "example": [ { "id": "_EAR0cJ7XB5k5grnmm0zeKGlVvVM9WCPy_", "date": "2016-10-18T16:53:32+00:00", "document": { "id": "72e7f8dd-1168-23ec-82ac-0e2b61663eb4", "dataEntityId": "Client", "isNewsletterOptIn": true, "createdBy": "81fc8b10-25b7-48de-b425-7b93554002cc" } }, { "id": "_E5SH9WXVvhPBNnbQtYAAGqrIysIeNYhV_", "date": "2016-09-08T20:11:42+00:00", "document": { "id": "72e7f8dd-1168-23ec-82ac-0e2b61663eb4", "dataEntityId": "Client", "isNewsletterOptIn": true, "createdBy": "81fc8b10-25b7-48de-b425-7b93554002cc" } } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/versions/{versionId}": { "get": { "tags": [ "Versions" ], "summary": "Get version", "description": "Returns the version of a document. \r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated.", "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": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getversion" } } } } }, "deprecated": false }, "put": { "tags": [ "Versions" ], "summary": "Update version", "description": "Updates the document's version value.\r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated.", "operationId": "Putversion", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "ID of the version to update", "required": true, "style": "simple", "schema": { "type": "string", "example": "_8sZcvyj4nng7FgA2RgtVVZmkIxb4Pbfe_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Client-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/Client/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "304": { "description": "Not Modified" } }, "deprecated": false } } }, "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": { "DocumentRequest": { "title": "DocumentRequest", "type": "object", "additionalProperties": { "type": "string", "description": "JSON document fields." }, "description": "This can be any pure JSON document. Add new _Key-Value_ pairs to test." }, "Using_fields_all": { "title": "Using_fields=_all", "required": [ "id", "accountId", "accountName", "dataEntityId" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the document." }, "accountId": { "type": "string", "description": "ID of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "dataEntityId": { "type": "string", "description": "Data entity name." } }, "example": { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "my-store-name", "dataEntityId": "Client" } }, "SaveschemabynameRequest": { "title": "SaveschemabynameRequest", "required": [ "properties" ], "type": "object", "description": "Schema.", "properties": { "properties": { "$ref": "#/components/schemas/Properties" } }, "example": { "properties": { "name": { "type": "string" } } } }, "GetSchemasResponse": { "title": "GetSchemasResponse", "required": [ "properties" ], "type": "object", "description": "Schema.", "properties": { "name": { "type": "string", "description": "Schema name." }, "schema": { "type": "object", "description": "Object with schema properties.", "properties": { "properties": { "$ref": "#/components/schemas/Properties" } } } }, "example": { "name": "testschema", "schema": { "properties": { "name": { "type": "string" } } } } }, "Properties": { "title": "Properties", "required": [ "name" ], "type": "object", "description": "Object containing schema properties.", "properties": { "name": { "$ref": "#/components/schemas/Name" } }, "example": { "name": { "type": "string" } } }, "Name": { "title": "Name", "required": [ "type" ], "type": "object", "description": "Property name.", "properties": { "type": { "type": "string", "description": "Type of property.", "enum": [ "array", "boolean", "integer", "number", "object", "string" ] } }, "example": { "type": "string" } }, "PutindicesRequest": { "title": "PutindicesRequest", "required": [ "name", "multiple", "fields" ], "type": "object", "properties": { "name": { "description": "Name to identify the index.", "type": "string" }, "multiple": { "description": "Determines whether the values need to be unique. If false, values must be unique.", "type": "boolean" }, "fields": { "description": "Comma-separated fields of the index.", "type": "string" } }, "example": { "name": "indexName", "multiple": false, "fields": "fieldName" } }, "Index": { "type": "object", "description": "Index information.", "properties": { "name": { "type": "string", "description": "Index name." }, "acronym": { "type": "string", "description": "Data entity name." }, "isGlobal": { "type": "boolean", "description": "Defines whether the index is global (`true`) or not (`false`).", "deprecated": true }, "multiple": { "type": "boolean", "description": "Determines whether the values need to be unique. If `false`, values must be unique." }, "fields": { "type": "string", "description": "Comma-separated fields of the index." } } }, "ValidatedocumentbyclustersRequest": { "title": "ValidatedocumentbyclustersRequest", "required": [ "name", "rule" ], "type": "object", "properties": { "name": { "type": "string" }, "rule": { "type": "string" } }, "example": { "name": "male", "rule": "gender=male" } }, "Listversion": { "title": "Listversion", "required": [ "id", "date" ], "type": "object", "properties": { "id": { "type": "string", "description": "Version ID." }, "date": { "type": "string", "description": "Date when the version was created in ISO 8601 format." }, "document": { "type": "object", "description": "Information about the document.", "properties": { "id": { "type": "string", "description": "Document ID." }, "dataEntityId": { "type": "string", "description": "Data entity name." }, "isNewsletterOptIn": { "type": "boolean", "description": "Indicates whether client otped to receive the store newsletter (`true`) or not (`false`).", "example": false, "nullable": true }, "createdBy": { "type": "string", "description": "ID of the user who created the document." } } } } }, "Getversion": { "title": "Getversion", "required": [ "id", "author", "document" ], "type": "object", "properties": { "id": { "type": "string", "description": "Version ID." }, "author": { "type": "string", "description": "ID of the user who created the version." }, "document": { "$ref": "#/components/schemas/Document" } }, "example": { "id": "cSIAceEelBEmSOqRkzJYLRQuGgi6.CqF", "author": "1f936e42-79b3-4e5b-91d2-da9a8af0b215", "document": { "id": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "dataEntityId": "Client", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "followers": [], "schemas": [ "testprofile", "testprofile2" ], "email": "clark.kent@examplemail.com" } } }, "Document": { "title": "Document", "required": [ "id", "dataEntityId", "accountId", "accountName", "followers" ], "type": "object", "properties": { "id": { "type": "string", "description": "ID of the document." }, "dataEntityId": { "type": "string", "description": "Data entity name." }, "accountId": { "type": "string", "description": "ID of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "followers": { "type": "array", "description": "Followers.", "deprecated": true, "items": { "type": "string" } }, "schemas": { "type": "array", "description": "Schemas which the document is compliant with.", "items": { "type": "string", "description": "Schema name." } }, "email": { "type": "string", "description": "User email." } }, "example": { "id": "my-id", "dataEntityId": "Client", "accountId": "my-account-id", "accountName": "my-account", "followers": [], "schemas": [ "testprofile", "testprofile2" ], "email": "clark.kent@examplemail.com" } }, "CreateDocumentResponse": { "required": [ "Id", "Href", "DocumentId" ], "type": "object", "properties": { "Id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "Href": { "type": "string", "description": "Document reference URL." }, "DocumentId": { "type": "string", "description": "ID of the document that was created." } } }, "documentResponse": { "required": [ "Id", "Href" ], "type": "object", "properties": { "Id": { "type": "string", "description": "ID of the document that was created or updated." }, "Href": { "type": "string", "description": "Document reference URL." } } }, "createUpdateProfileRequests": { "type": "object", "properties": { "email": { "type": "string", "description": "Client email address.", "example": "clark.kent@examplemail.com", "nullable": true }, "firstName": { "type": "string", "description": "Client first name.", "example": "Clark", "nullable": true }, "lastName": { "type": "string", "description": "Client last name.", "example": "Kent", "nullable": true }, "phone": { "type": "string", "description": "Client telephone number.", "example": "+12025550195", "nullable": true }, "documentType": { "type": "string", "description": "Client document type.", "example": "CPF", "nullable": true }, "document": { "type": "string", "description": "Client document.", "example": "12345678900", "nullable": true }, "isCorporate": { "type": "boolean", "description": "Indicates whether client is corporate.", "example": false, "nullable": true }, "isNewsletterOptIn": { "type": "boolean", "description": "Indicates whether client otped to receive the store newsletter (`true`) or not (`false`).", "example": false, "nullable": true }, "localeDefault": { "type": "string", "description": "Default locale, used to set store language and currency, for example.", "example": "en-US", "nullable": true } } }, "createUpdateAddressRequests": { "type": "object", "properties": { "addressName": { "type": "string", "description": "Address name.", "example": "My house", "nullable": true }, "addressType": { "type": "string", "description": "Type of address. For example, `Residential` or `Pickup`, among others.", "example": "residential", "nullable": true }, "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order.", "example": "Clark Kent.", "nullable": true }, "city": { "type": "string", "description": "City of the shipping address.", "example": "Rio de Janeiro", "nullable": true }, "state": { "type": "string", "description": "State of the shipping address.", "example": "Rio de Janeiro", "nullable": true }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address.", "example": "BRA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal Code.", "example": "12345-000", "nullable": true }, "street": { "type": "string", "description": "Street of the address.", "example": "Praia de Botafogo", "nullable": true }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address.", "example": "300", "nullable": true }, "neighborhood": { "type": "string", "description": "Neighborhood of the address.", "example": "Botafogo", "nullable": true }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "example": "3rd floor", "nullable": true }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "example": "Grey building", "nullable": true }, "userId": { "type": "string", "description": "ID of the customer to whom the address belongs.", "example": "7e03m794-a33a-11e9-84rt6-0adfa64s5a8e", "nullable": true } } } }, "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" } }, "dataEntityName": { "name": "dataEntityName", "in": "path", "required": true, "description": "Name of the data entity. Examples of native data entities you can use are `Client` for client profiles and `Address` for client addresses.", "schema": { "type": "string", "example": "Client" } }, "_schema": { "name": "_schema", "in": "query", "description": "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.", "required": false, "style": "form", "schema": { "type": "string", "example": "schema" } }, "id": { "name": "id", "in": "path", "description": "ID of the Document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, "versionId": { "name": "versionId", "in": "path", "description": "ID of the version to update.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_8sZcvyj4nng7FgA2RgtVVZmkIxb4Pbfe_" } }, "_where": { "name": "_where", "in": "query", "description": "Defines a clause the document must comply with.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, "index_name": { "name": "index_name", "in": "path", "description": "Name of the index.", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{index_name}}" } }, "schemaName": { "name": "schemaName", "in": "path", "description": "Name of the schema.", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{schema}}" } }, "REST-Range": { "name": "REST-Range", "in": "header", "description": "Defines the collection of documents to be returned. A range within the collection limited by 100 documents per query.", "required": true, "style": "simple", "schema": { "type": "string", "example": "resources=0-10" } }, "_fields": { "name": "_fields", "in": "query", "description": "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.", "required": false, "style": "form", "schema": { "type": "string", "example": "email,firstName,document" } }, "_keyword": { "name": "_keyword", "in": "query", "description": "String to search. Use quotes for a partial query. For example, `_keyword=Maria` or `_keyword=\"Maria\"`.", "required": false, "style": "form", "schema": { "type": "string", "example": "String to search" } }, "_sort": { "name": "_sort", "in": "query", "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.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } }, "_token": { "name": "_token", "in": "query", "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.", "required": false, "style": "form", "schema": { "type": "string", "example": "123456" } }, "_size": { "name": "_size", "in": "query", "description": "Inform the number of documents per request. Maximum value of `1000`.", "required": false, "style": "form", "schema": { "type": "integer", "default": 100 } } } }, "tags": [ { "name": "Documents" }, { "name": "Search" }, { "name": "Scroll" }, { "name": "Schemas" }, { "name": "Indices" }, { "name": "Clusters" }, { "name": "Versions" }, { "name": "Customer profiles" }, { "name": "Addresses" } ] }