From 2564730935bbb6cf8c557966c59d53380cfeada8 Mon Sep 17 00:00:00 2001 From: decobot Date: Thu, 11 Dec 2025 17:58:42 -0300 Subject: [PATCH] feat(vtex): add schema parameter to Masterdata loaders and actions --- vtex/actions/masterdata/createDocument.ts | 7 ++-- vtex/actions/masterdata/updateDocument.ts | 7 ++-- vtex/loaders/masterdata/searchDocuments.ts | 7 +++- vtex/utils/client.ts | 3 ++ vtex/utils/openapi/vcs.openapi.gen.ts | 39 +++++++++++++++++++++- vtex/utils/openapi/vcs.openapi.json | 37 ++++++++++++++++++++ 6 files changed, 92 insertions(+), 8 deletions(-) diff --git a/vtex/actions/masterdata/createDocument.ts b/vtex/actions/masterdata/createDocument.ts index 6f8914ae7..1982d077f 100644 --- a/vtex/actions/masterdata/createDocument.ts +++ b/vtex/actions/masterdata/createDocument.ts @@ -5,6 +5,7 @@ import type { CreateNewDocument } from "../../utils/types.ts"; export interface Props { data: Record; acronym: string; + schema?: string; isPrivateEntity?: boolean; } @@ -20,7 +21,7 @@ const action = async ( /* no-explicit-any */ ): Promise => { const { vcs, vcsDeprecated } = ctx; - const { data, acronym, isPrivateEntity } = props; + const { data, acronym, isPrivateEntity, schema } = props; const { cookie } = parseCookie(req.headers, ctx.account); const requestOptions = { @@ -35,11 +36,11 @@ const action = async ( const response = await (isPrivateEntity ? vcs[`POST /api/dataentities/:acronym/documents`]( - { acronym }, + schema ? { acronym, _schema: schema } : { acronym }, requestOptions, ) : vcsDeprecated[`POST /api/dataentities/:acronym/documents`]( - { acronym }, + schema ? { acronym, _schema: schema } : { acronym }, requestOptions, )); diff --git a/vtex/actions/masterdata/updateDocument.ts b/vtex/actions/masterdata/updateDocument.ts index 6a8add491..78f3484f7 100644 --- a/vtex/actions/masterdata/updateDocument.ts +++ b/vtex/actions/masterdata/updateDocument.ts @@ -10,6 +10,7 @@ export interface Props { acronym: string; data: Record; createIfNotExists?: boolean; + schema?: string; } /** @@ -24,7 +25,7 @@ const action = async ( ctx: AppContext, ): Promise => { const { vcs } = ctx; - const { id, data, acronym, createIfNotExists } = props; + const { id, data, acronym, createIfNotExists, schema } = props; const { cookie } = parseCookie(req.headers, ctx.account); const requestOptions = { @@ -39,11 +40,11 @@ const action = async ( const response = await (createIfNotExists ? vcs["PATCH /api/dataentities/:acronym/documents"]( - { acronym }, + schema ? { acronym, _schema: schema } : { acronym }, requestOptions, ) : vcs["PATCH /api/dataentities/:acronym/documents/:id"]( - { acronym, id }, + schema ? { acronym, id, _schema: schema } : { acronym, id }, requestOptions, )); diff --git a/vtex/loaders/masterdata/searchDocuments.ts b/vtex/loaders/masterdata/searchDocuments.ts index 1dbfdc999..4956a50fa 100644 --- a/vtex/loaders/masterdata/searchDocuments.ts +++ b/vtex/loaders/masterdata/searchDocuments.ts @@ -16,6 +16,10 @@ interface Props { * @description Specification of filters. */ where?: string; + /** + * @description Schema of the data entity. + */ + schema?: string; /** * @description Inform a field name plus ASC to sort results by this field value in ascending order or DESC to sort by descending order. */ @@ -47,7 +51,7 @@ export default async function loader( ctx: AppContext, ): Promise { const { vcs } = ctx; - const { acronym, fields, where, sort, skip = 0, take = 10 } = props; + const { acronym, fields, where, sort, skip = 0, take = 10, schema } = props; const { cookie } = parseCookie(req.headers, ctx.account); const limits = resourceRange(skip, take); @@ -56,6 +60,7 @@ export default async function loader( _fields: fields, _where: where, _sort: sort, + _schema: schema, }, { headers: { accept: "application/vnd.vtex.ds.v10+json", diff --git a/vtex/utils/client.ts b/vtex/utils/client.ts index eccc94f70..b485045ea 100644 --- a/vtex/utils/client.ts +++ b/vtex/utils/client.ts @@ -289,6 +289,9 @@ export interface VTEXCommerceStable { }; }; "POST /api/dataentities/:acronym/documents": { + searchParams: { + _schema?: string; + }; response: CreateNewDocument; body: Record; }; diff --git a/vtex/utils/openapi/vcs.openapi.gen.ts b/vtex/utils/openapi/vcs.openapi.gen.ts index bf79990dc..8e8f2581c 100644 --- a/vtex/utils/openapi/vcs.openapi.gen.ts +++ b/vtex/utils/openapi/vcs.openapi.gen.ts @@ -736,6 +736,10 @@ searchParams: { * 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. */ _fields?: string +/** + * 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. + */ +_schema?: string /** * Specification of filters. */ @@ -861,6 +865,12 @@ to?: number * Create a new document */ "POST /api/dataentities/:acronym/documents": { +searchParams: { +/** + * 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. + */ +_schema?: string +} body: { anyProperty?: string } @@ -890,6 +900,12 @@ DocumentId?: string * >❗ 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. */ "PATCH /api/dataentities/:acronym/documents": { +searchParams: { +/** + * 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. + */ +_schema?: string +} body: { /** * Unique identifier of the document to be created. @@ -927,6 +943,10 @@ searchParams: { * 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. */ _fields?: string +/** + * 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. + */ +_schema?: string } response: Document } @@ -975,6 +995,12 @@ response: Document * >❗ 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. */ "PUT /api/dataentities/:acronym/documents/:id": { +searchParams: { +/** + * 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. + */ +_schema?: string +} /** * Object with document fields and their respective values. */ @@ -1003,7 +1029,12 @@ body: { * >❗ 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. */ "DELETE /api/dataentities/:acronym/documents/:id": { - +searchParams: { +/** + * 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. + */ +_schema?: string +} } /** * Updates a subset of fields of a document, without impacting the other fields. @@ -1025,6 +1056,12 @@ body: { * >❗ 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. */ "PATCH /api/dataentities/:acronym/documents/:id": { +searchParams: { +/** + * 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. + */ +_schema?: string +} /** * Object with the fields to be updated and their respective values. */ diff --git a/vtex/utils/openapi/vcs.openapi.json b/vtex/utils/openapi/vcs.openapi.json index d9b6269ba..5b480df75 100644 --- a/vtex/utils/openapi/vcs.openapi.json +++ b/vtex/utils/openapi/vcs.openapi.json @@ -971,6 +971,17 @@ "example": "email,firstName,document" } }, + { + "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" + } + }, { "name": "_where", "in": "query", @@ -1557,6 +1568,17 @@ "schema": { "type": "string" } + }, + { + "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" + } } ], "requestBody": { @@ -1614,6 +1636,9 @@ }, { "$ref": "#/components/parameters/acronym" + }, + { + "$ref": "#/components/parameters/_schema" } ], "requestBody": { @@ -1685,6 +1710,9 @@ }, { "$ref": "#/components/parameters/fields" + }, + { + "$ref": "#/components/parameters/_schema" } ], "responses": { @@ -1745,6 +1773,9 @@ }, { "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/_schema" } ], "requestBody": { @@ -1810,6 +1841,9 @@ }, { "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/_schema" } ], "requestBody": { @@ -1851,6 +1885,9 @@ }, { "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/_schema" } ], "responses": {