This app is no longer maintained by VTEX. This means it will not be updated, and support and maintenance are no longer provided.

The Safedata app provides a configurable middleware to retrieve and save Master Data v1 and v2 information directly on the front-end or through another back-end application using shopper token authentication, rather than application keys.

This app works by acting as an validation layer on top of Master Data API to ensure data is being queried only by the user who owns it. The app makes the decision if the data can be returned or edited based on who is trying to access it, so it will only allow access to the information of the shopper who is logged in.

Relevant use cases include forms, such as warranty information submission, newsletter subscription, buyer's club registration or reseller registration.

You can install Safedata through the VTEX App Store or by running the following command on VTEX IO CLI:

Upon installation, Safedata routes become instantly available to use with default entities CL (Client) and AD (Address). Other entities can be set up through app settings.

The process is based on the CL entity, which is used as a guide to identify the user. First, we reach out to VTEX ID to confirm the StoreUserAuthToken is valid and get the user email. Then we retrieve only the necessary fields on the CL entity to ensure the user is retrieving or modifying only documents that belongs to them.

This is done through a field comparison between CL and the entity is being queried. For instance, when searching for documents of the AD entity, we compare their userId to the id found in the CL entity, and the action is only allowed if they match.

The comparison fields must be searchable on the Master Data fields configuration. However, they do not have to be public. We do not recommend making any fields public.

The basic configurations for CL and AD entities are set by default, as illustrated below, but can be changed by using the app settings interface.

To enable other Master Data entities to work with Safedata, configure them on the app's settings as explained below:

1. On VTEX Admin, go to Apps > Extensions Hub > App Management.

2. Search for Safedata.

3. Click Settings.

4. Click + Add more.

5. Fill in the required information:

   • Entity acronym on Master Data
   • Field to match on current entity
   • Field to match on CL entity
   • Allow creating objects anonymously?

6. Click Save.

You can delete entity configurations by clicking the trash icon in their row.

To query Master Data information using Safedata, you need to replace api/dataentities for api/io/safedata in Master Data API v1 and Master Data API v2 routes.

For example, if you need to query the AD entity by a specific addressName, the request would be: GET https://apiexamples.myvtex.com/api/io/safedata/AD/search?_where=addressName=12345

Safedata supports the following routes:

Action	Original route	Safedata route
Get document	GET /api/dataentities/{dataEntityName}/documents/{documentId}	GET /api/io/safedata/{dataEntityName}/documents/{documentId}
Search documents	GET /api/dataentities/{dataEntityName}/search	GET /api/io/safedata/{dataEntityName}/search
Create document	POST /api/dataentities/{dataEntityName}/documents	POST /api/io/safedata/{dataEntityName}/documents
Create document with custom ID or update entire document	PUT /api/dataentities/{dataEntityName}/documents/{documentId}	PUT /api/io/safedata/{dataEntityName}/documents/{documentId}
Delete document	DELETE /api/dataentities/{dataEntityName}/documents/{documentId}	DELETE /api/io/safedata/{dataEntityName}/documents/{documentId}
Update partial document	PATCH /api/dataentities/{dataEntityName}/documents/{documentId}	PATCH /api/io/safedata/{dataEntityName}/documents/{documentId}

All underscore query parameters are supported (_where, _fields, _schema, and so on).

If the user is logged out and tries to fetch information that does not belong to them, the middleware returns a status 403. It is possible to verify these requests through DevTools. Another status that the middleware returns are:

Response	Meaning
401 Unauthorized	No token informed (not logged in) or invalid token.
403 Forbidden	Operation not allowed. The user is trying to retrieve or edit data that is not their own.
404 Not Found	Occurs when the user is not found or when a document search does not return data with the specified filter (Safedata always filters the search to return only documents belonging to the shoppers who is logged in).
200 OK	Successful request.

Safedata also provides a patchDocument mutation in GraphQL which enables React components to create or update documents in Master Data.

You can test it yourself using the GraphQL IDE.

Example mutation

This example demonstrates how to use the patchDocument mutation to create a document with a new email value:

Input Fields

• entity (String!): The entity type of the document to update.
• document (DocumentInput!): The document fields to update.

DocumentInput Fields

• fields ([DocumentFieldInput!]!): An array of fields to update in the document, with a key/value pair representing each field.

DocumentFieldInput Fields

• key (String!): The key of the field to update.
• value (String!): The new value of the field to update.

Example query variables

Example result

When a shopper is making their first purchase, the CL entity may be created preemptively if the store has specific customizations to include new fields in the checkout process, i.e., birth date. This might cause issues since Safedata forbids customers to change personal data when they are not logged in.

To avoid this problem, you can add the query parameter _orderFormId so Safedata can ensure the customer can safely change their information during their first checkout. See the following example:

PATCH /safedata/CL/documents?_orderFormId=7217c9c7413142dd93e3b715f95cd03d

When this request is called for the first time the user does not exist, so it is allowed to be created anonymously.

In subsequent calls, Safedata checks the _orderFormId to ensure the user was created in this checkout session, so they can update their information without asking for credentials.

This allows users to update their personal information during the checkout process without logging in only during the first purchase.

Once the first purchase is finished, a complete profile is generated, and in order to update this information again the user has to log in.

Only the PATCH /api/io/safedata/{dataEntityName}/documents/{documentId} route supports the _orderFormId parameter, and it only works with entities that contain an email field in their schema.