{"note":"OpenAPI conversion -- returning structured metadata","name":"vtex-local-masterdata-api","description":"Master Data API - v1","version":"1.0","base_url":"https://apiexamples.vtexcommercestable.com.br","endpoints":26,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Master Data API - v1\n@base https://apiexamples.vtexcommercestable.com.br\n@version 1.0\n@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header\n@common_fields {Content-Type: str=application/json # Type of the content being sent., Accept: str=application/vnd.vtex.ds.v10+json # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.}\n@endpoints 26\n@hint download_for_search\n@toc api(26)\n\n@endpoint GET /api/dataentities\n@desc List data entities\n@returns(200) OK\n@errors {403: Forbidden}\n\n@endpoint GET /api/dataentities/{acronym}\n@desc Get data entity structure\n@required {acronym: str # Data entity acronym.}\n@returns(200) {acronym: str, name: str, primaryKeyType: str, allowGetAll: bool, fields: [map]} # OK\n@errors {403: Forbidden}\n\n@endpoint POST /api/dataentities/{acronym}/documents\n@desc Create new document\n@required {acronym: str # Two-letter string that identifies the data entity.}\n@optional {{fieldName}: str # Field name.}\n@returns(201) {id: str, href: str, documentId: str} # Created\n@example_request {\"Boolean\":true,\"Currency\":2.5,\"Date\":\"1992-11-17\",\"Date_Time\":\"2016-09-14T19:21:01.3163733Z\",\"Decimal\":2.5,\"Email\":\"meu@email.com\",\"Integer\":1000000,\"Long\":1000000000,\"Percent\":85.42,\"Time\":\"23:50\",\"URL\":\"http://www.vtex.com\",\"Varchar10\":\"Lorem ipsu\",\"Varchar50\":\"Lorem ipsum dolor sit amet, consectetur adipiscing\",\"Varchar750\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\",\"Varchar100\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\",\"Relationship\":\"5eb31afb-7ab0-11e6-94b4-0a44686e393f\",\"Text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\"}\n\n@endpoint PATCH /api/dataentities/{acronym}/documents\n@desc Create partial document\n@required {acronym: str # Two-letter string that identifies the data entity.}\n@optional {id: str # Unique identifier of the document to be created., {fieldName}: str # Field(s) to be filled in and its respective value(s).}\n@returns(201) {id: str, href: str, documentId: str} # Created\n@errors {304: Not Modified}\n@example_request {\"id\":\"4e4c55ac-e491-11e6-94f4-0ac138d2d42e\",\"addressName\":\"4726026151251\"}\n\n@endpoint GET /api/dataentities/{acronym}/documents/{id}\n@desc Get document\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@optional {_fields: str # Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used.}\n@returns(200) {{customProperty}: str, id: str, accountId: str, accountName: str, dataEntityId: str} # OK\n@errors {403: Forbidden}\n\n@endpoint PUT /api/dataentities/{acronym}/documents/{id}\n@desc Create document with custom ID or update entire document\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@optional {{fieldName}: str # Field name and value.}\n@returns(204) No Content\n@example_request {\"Boolean\":true,\"Currency\":2.5,\"Date\":\"1992-11-17\",\"Date_Time\":\"2016-09-14T19:21:01.3163733Z\",\"Decimal\":2.5,\"Email\":\"meu@email.com\",\"Integer\":1000000,\"Long\":1000000000,\"Percent\":85.42,\"Time\":\"23:50\",\"URL\":\"http://www.vtex.com\",\"Varchar10\":\"Lorem ipsu\",\"Varchar50\":\"Lorem ipsum dolor sit amet, consectetur adipiscing\",\"Varchar750\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\",\"Varchar100\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\",\"Relationship\":\"5eb31afb-7ab0-11e6-94b4-0a44686e393f\",\"Text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\"}\n\n@endpoint PATCH /api/dataentities/{acronym}/documents/{id}\n@desc Update partial document\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@returns(204) No Content\n@example_request {\"addressName\":\"4726026151253\"}\n\n@endpoint DELETE /api/dataentities/{acronym}/documents/{id}\n@desc Delete document\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@returns(204) No Content\n\n@endpoint GET /api/dataentities/{acronym}/documents/{id}/versions\n@desc List versions\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@returns(200) OK\n\n@endpoint GET /api/dataentities/{acronym}/documents/{id}/versions/{versionId}\n@desc Get version\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document., versionId: str # Unique identifier of the version to retrieve.}\n@returns(200) {id: str, author: str, document: map{{customProperty}: str, id: str, accountId: str, accountName: str, dataEntityId: str}} # OK\n\n@endpoint PUT /api/dataentities/{acronym}/documents/{id}/versions/{versionId}\n@desc Update version\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document., versionId: str # Unique identifier of the version to update.}\n@returns(200) {Id: str, Href: str} # OK\n@errors {304: Not Modified  This response happens when the versionId informed in the path already corresponds to the current version of the document.}\n\n@endpoint GET /api/dataentities/{acronym}/scroll\n@desc Scroll documents\n@required {acronym: str # Two-letter string that identifies the data entity.}\n@optional {_fields: str # Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used., _where: str # Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`)., _sort: str # Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order., _size: str # Maximum amount of documents returned per request. The maximum value you can set is `1000`., _token: str # Value of the `X-VTEX-MD-TOKEN` token obtained in the response header of the first request, necessary on subsequent requests to continue scrolling through documents. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.}\n@returns(200) OK\n@errors {400: Bad Request, 429: Too Many Requests  Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.}\n\n@endpoint GET /api/dataentities/{acronym}/search\n@desc Search documents\n@required {REST-Range: str # Specifies the range of documents to be returned in the response. The value should follow the format `resources={x}-{y}`, where: * `x`: Index of the first document in the returned array. * `y`: Index of the last document in the returned array + 1.  This field controls pagination by defining the subset of documents to be retrieved. The maximum number of documents returned per query is limited to 100. For example, `resources=0-10` returns the first 10 documents., acronym: str # Two-letter string that identifies the data entity.}\n@optional {_fields: str # Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used., _where: str # Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`)., _sort: str # Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.}\n@returns(200) OK\n@errors {503: Service Unavailable  Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.}\n\n@endpoint GET /api/dataentities/{acronym}/documents/{id}/{field}/attachments/{file-name}\n@desc Retrieve attachment\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document., field: str # Name of the field where the file is saved, as it appears on VTEX Admin., file-name: str # File name and extension.}\n@returns(200) OK\n\n@endpoint POST /api/dataentities/{acronym}/documents/{id}/{field}/attachments\n@desc Save attachment\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document., field: str # Name of the field to attach the file to, as it appears in VTEX Admin.}\n@returns(204) No Content\n\n@endpoint POST /api/dataentities/{acronym}/documents/{id}/clusters\n@desc Validate document by clusters\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@returns(200) OK\n@example_request [{\"name\":\"male\",\"rule\":\"gender=male\"},{\"name\":\"complex\",\"rule\":\"((gender=male AND percent=0.35) AND any is null) AND (name=*go*)\"},{\"name\":\"complex2\",\"rule\":\"((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)\"},{\"name\":\"createdIn\",\"rule\":\"createdIn between 2015-10-28 AND 2015-10-30\"}]\n\n@endpoint PUT /api/dataentities/{acronym}/documents/{id}/score\n@desc Update scores\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document.}\n@returns(204) No Content\n@example_request [{\"field\":\"carttag\",\"key\":\"Payment\",\"point\":1,\"until\":\"10m\"},{\"field\":\"scoretest\",\"key\":\"Point 1\",\"point\":1,\"until\":\"1d\"}]\n\n@endpoint PUT /api/dataentities/{acronym}/documents/{id}/score/{field-name}\n@desc Update score by field\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document., field-name: str # Name of the field to score., key: str # Key name., point: int(int32) # Amount of points to be added to the score., until: str # Amount of time the added points will be valid for.}\n@returns(204) No Content\n@example_request {\"key\":\"first key\",\"point\":1,\"until\":\"10m\"}\n\n@endpoint DELETE /api/dataentities/{acronym}/documents/{id}/score/{field-name}\n@desc Delete score by field\n@required {acronym: str # Two-letter string that identifies the data entity., id: str # Unique identifier of the document., field-name: str # Name of the field to remove a key from., key: str # Key name.}\n@returns(204) No Content\n@example_request {\"key\":\"first key\"}\n\n@endpoint POST /api/dataentities/CL/documents\n@desc Create new customer profile\n@optional {_schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters., email: str # Client email address. This field is required for B2B Buyer Portal., firstName: str # Client first name. This field is required for B2B Buyer Portal., lastName: str # Client last name. This field is required for B2B Buyer Portal., phone: str # Client telephone number., documentType: str # Client document type. This field is required for B2B Buyer Portal., document: str # Client document. This field is required for B2B Buyer Portal., isCorporate: bool # Indicates whether client is corporate. For the B2B Buyer Portal, this field is required and always `true`., isNewsletterOptIn: bool # Indicates whether client otped to receive the store newsletter (`true`) or not (`false`)., localeDefault: str # Default locale, used to set store language and currency, for example., corporateDocument: str # The business document of the contract. This field is recommended for B2B Buyer Portal., homePhone: str # The home phone number of the contract. This field is recommended for B2B Buyer Portal., cellPhone: str # The cell phone number of the contract. This field is recommended for B2B Buyer Portal., corporateName: str # The corporate name of the contract. This field is required for B2B Buyer Portal., tradeName: str # The trade name (\"doing business as\") of the contract. This field is recommended for B2B Buyer Portal., stateRegistration: str # The state registration of the contract. This field is recommended for B2B Buyer Portal., isFreeStateRegistration: bool # Indicates if the state registration is free. This field is recommended for B2B Buyer Portal., priceTables: str # Price tables associated with the contract, separated by commas. This field is recommended for B2B Buyer Portal., restrictions: map{vtex.catalog: map, vtex.checkout: map, vtex.payments: map} # Object with restriction definitions for `vtex.catalog`, `vtex.checkout`, and `vtex.payments`. This field is recommended for B2B Buyer Portal.}\n@returns(200) {Id: str, Href: str} # OK\n@example_request {\"email\":\"clark.kent@examplemail.com\",\"firstName\":\"Clark\",\"lastName\":\"Kent\",\"phone\":\"+12025550195\",\"documentType\":\"CPF\",\"document\":\"12345678900\",\"isCorporate\":false,\"isNewsletterOptIn\":false,\"localeDefault\":\"en-US\"}\n\n@endpoint PATCH /api/dataentities/CL/documents/{id}\n@desc Update customer profile\n@required {id: str # Unique identifier of the document.}\n@optional {_schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters., email: str # Client email address. This field is required for B2B Buyer Portal., firstName: str # Client first name. This field is required for B2B Buyer Portal., lastName: str # Client last name. This field is required for B2B Buyer Portal., phone: str # Client telephone number., documentType: str # Client document type. This field is required for B2B Buyer Portal., document: str # Client document. This field is required for B2B Buyer Portal., isCorporate: bool # Indicates whether client is corporate. For the B2B Buyer Portal, this field is required and always `true`., isNewsletterOptIn: bool # Indicates whether client otped to receive the store newsletter (`true`) or not (`false`)., localeDefault: str # Default locale, used to set store language and currency, for example., corporateDocument: str # The business document of the contract. This field is recommended for B2B Buyer Portal., homePhone: str # The home phone number of the contract. This field is recommended for B2B Buyer Portal., cellPhone: str # The cell phone number of the contract. This field is recommended for B2B Buyer Portal., corporateName: str # The corporate name of the contract. This field is required for B2B Buyer Portal., tradeName: str # The trade name (\"doing business as\") of the contract. This field is recommended for B2B Buyer Portal., stateRegistration: str # The state registration of the contract. This field is recommended for B2B Buyer Portal., isFreeStateRegistration: bool # Indicates if the state registration is free. This field is recommended for B2B Buyer Portal., priceTables: str # Price tables associated with the contract, separated by commas. This field is recommended for B2B Buyer Portal., restrictions: map{vtex.catalog: map, vtex.checkout: map, vtex.payments: map} # Object with restriction definitions for `vtex.catalog`, `vtex.checkout`, and `vtex.payments`. This field is recommended for B2B Buyer Portal.}\n@returns(200) {Id: str, Href: str} # OK\n@example_request {\"email\":\"clark.kent@examplemail.com\",\"firstName\":\"Clark\",\"lastName\":\"Kent\"}\n\n@endpoint DELETE /api/dataentities/CL/documents/{id}\n@desc Delete customer profile\n@required {id: str # Unique identifier of the document.}\n@returns(204) No Content\n\n@endpoint POST /api/dataentities/AD/documents\n@desc Create new customer address\n@optional {_schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters., addressName: str # Address name., addressLabel: str # Custom label for the address used by shoppers and buyer org managers., addressType: str(commercial/invoice) # Type of address. For example, `Residential` or `Pickup`, among others. For B2B Buyer Portal, this field is required and its possible values are `commercial` for shipping or `invoice` for billing., receiverName: str # Name of the person who is going to receive orders at this address. This field is required for B2B Buyer Portal., city: str # City of the shipping address. This field is required for B2B Buyer Portal., state: str # State of the shipping address. The state or province of the address. This field is required for B2B Buyer Portal., country: str # Three letter ISO code of the country of the shipping address. This field is required for B2B Buyer Portal., postalCode: str # Postal Code. The format must be compatible with the country postal code format (e.g., `00000` for addresses in the USA). This field is required for B2B Buyer Portal., street: str # The street name of the address. This field is required for B2B Buyer Portal., number: str # Number of the building, house or apartment in the shipping address. This field is required for B2B Buyer Portal., neighborhood: str # Neighborhood of the address., complement: str # Additional information or details that help identify or locate the shipping address, such as apartment number, suite, floor, or unit (if applicable)., reference: str # Optional reference point or nearby landmark to help locate the shipping address during delivery (e.g., next to a park or behind a building)., geoCoordinate: str # The geographical coordinates of the address (optional). This field is recommended for B2B Buyer Portal., userId: str # ID of the customer to whom the address belongs. This information is the `id` returned by the customer profile (or contract) creation request. This field is required for B2B Buyer Portal.}\n@returns(200) {Id: str, Href: str} # OK\n@example_request {\"addressName\":\"My house\",\"addressLabel\":\"NC Office\",\"addressType\":\"commercial\",\"receiverName\":\"Clark Kent\",\"city\":\"Raleigh\",\"state\":\"NC\",\"country\":\"USA\",\"postalCode\":\"12345\",\"street\":\"Main Street\",\"number\":\"300\",\"neighborhood\":\"Downtown\",\"complement\":\"3rd floor\",\"reference\":\"Next to the park\",\"geoCoordinate\":\"40.7128,-74.0060\",\"userId\":\"7e03m794-a33a-11e9-84rt6-0adfa64s5a8e\"}\n\n@endpoint GET /api/dataentities/AD/documents/{addressId}\n@desc Get address by ID\n@required {addressId: str # ID of the address to retrieve., _fields: str=_all # Specifies that all fields of the document should be included in the response.}\n@returns(200) {addressLabel: str?, addressType: str?, city: str?, complement: str?, country: str?, countryfake: str?, geoCoordinate: str?, neighborhood: str?, number: str?, postalCode: str?, receiverName: str?, reference: str?, state: str?, street: str?, userId: str?, id: str?, accountId: str?, accountName: str?, dataEntityId: str?, createdBy: str?, createdIn: str?, updatedBy: str?, updatedIn: str?, lastInteractionBy: str?, lastInteractionIn: str?, followers: [str]?, tags: [str]?, auto_filter: str?} # OK\n\n@endpoint PATCH /api/dataentities/AD/documents/{addressId}\n@desc Update address by ID\n@required {addressId: str # ID of the address to update.}\n@optional {_schema: str # Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters., addressName: str # Address name., addressLabel: str # Custom label for the address used by shoppers and buyer org managers., addressType: str(commercial/invoice) # Type of address. For example, `Residential` or `Pickup`, among others. For B2B Buyer Portal, this field is required and its possible values are `commercial` for shipping or `invoice` for billing., receiverName: str # Name of the person who is going to receive orders at this address. This field is required for B2B Buyer Portal., city: str # City of the shipping address. This field is required for B2B Buyer Portal., state: str # State of the shipping address. The state or province of the address. This field is required for B2B Buyer Portal., country: str # Three letter ISO code of the country of the shipping address. This field is required for B2B Buyer Portal., postalCode: str # Postal Code. The format must be compatible with the country postal code format (e.g., `00000` for addresses in the USA). This field is required for B2B Buyer Portal., street: str # The street name of the address. This field is required for B2B Buyer Portal., number: str # Number of the building, house or apartment in the shipping address. This field is required for B2B Buyer Portal., neighborhood: str # Neighborhood of the address., complement: str # Additional information or details that help identify or locate the shipping address, such as apartment number, suite, floor, or unit (if applicable)., reference: str # Optional reference point or nearby landmark to help locate the shipping address during delivery (e.g., next to a park or behind a building)., geoCoordinate: str # The geographical coordinates of the address (optional). This field is recommended for B2B Buyer Portal., userId: str # ID of the customer to whom the address belongs. This information is the `id` returned by the customer profile (or contract) creation request. This field is required for B2B Buyer Portal.}\n@returns(200) {Id: str, Href: str} # OK\n@example_request {\"addressName\":\"NC Office\",\"addressLabel\":\"NC Office\",\"postalCode\":\"48226\",\"street\":\"Toringon Street\",\"number\":\"11\",\"neighborhood\":\"\",\"complement\":\"\",\"city\":\"Raleigh\",\"state\":\"NC\",\"country\":\"USA\",\"receiverName\":\"Backpack-Klub-LLC\",\"geoCoordinate\":\"\",\"addressType\":\"commercial\",\"reference\":\"Grey building\",\"userId\":\"2da4e9ab-050b-11f0-b37f-d6617047d485\"}\n\n@endpoint DELETE /api/dataentities/AD/documents/{addressId}\n@desc Delete address by ID\n@required {addressId: str # ID of the address to be deleted.}\n@returns(204) No Content\n\n@end\n"}