Handy VTEX library for NodeJs
This module wrapps the most common used VTEX APIs requests. Currently containing:
- Master Data
- Search
- Post
- Delete
- Patch
- OMS
- Load Order
- List Orders
- Cancel order
- Catalog
- Load Product
- Load Product by RefId
- Load SKU
- Checkout
- Load Orderform by Id
- Giftcard
- Create Giftcard
- Logistics
- ListReservationById
- Utils
- uuid
npm i vtex-commons
Here's a example of how to use the Master Data's Search
const VTEX = require('vtex-commons')
mondule.exports = async () => {
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.MasterData().Search({
entity : 'CL',
rule : '[email protected]',
fields : '_all'
})
}
You might be wondering: "Where are the key and token required to perform a private request? I can't see them in the code!"
You're right, they aren't in the code. And if you keep your credentials within your code, you're going to Developers Hell.
When you instanciate the module, it assumes you have at least two enviroment variables already set:
- APP_KEY
- APP_TOKEN
Therefore, there's no need to write them down in your code. If you need to use anothers name for this variables other then the provided, you'll be able to overwrite the default ones. More on that in a minute.
This method requires an object with four parameters:
- entity (this is the acronym of the entity/table set in the Master Data admin)
- rule (this is the query you want to perform)
- fields (a string with comma separated field names or '_all' to get all the public fields)
- range (optional - a string with the desired range of results. Ex.: "0-30". Default: "0-10")
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.MasterData().Search({
entity : 'CL',
rule : '[email protected]',
fields : '_all'
})
This method requires an object with two required parameters:
- entity (required - this is the acronym of the entity/table set in the Master Data admin)
- data (required - an object or stringified object with the data you want to post)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.MasterData().Post({
entity : 'CL',
data : {name : 'Jane'}
})
This method requires an object with two parameters:
- entity (this is the acronym of the entity/table set in the Master Data admin)
- id (a string with the id of the register you want to delete (this id can be gotten with the search method))
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.MasterData().Delete({
entity : 'CL',
id : '54353fsdf-42342rfsfsfs-23rfdsfsdfds'
})
This method requires an object with three parameters:
- entity (this is the acronym of the entity/table set in the Master Data admin)
- id (a string with the id of the register you want to delete (this id can be gotten with the search method))
- data (an object or stringified object with the data you want to update)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.MasterData().Patch({
entity : 'CL',
data : {name : 'Jane'}
id : '54353fsdf-42342rfsfsfs-23rfdsfsdfds'
})
This method requires an object with one parameter:
- orderId (a string with the id from the order you want to load)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.OMS().LoadOrder({
orderId : '54353fsdf-01'
})
This method requires an object with one parameter:
- filter (this is a string you can get filtering the order in the OMS admin. You'll nedd to copy everything begining from 'orderBy' Ex.: https://dummystore.myvtex.com/admin/checkout/#/orders/1176931852456-01?orderBy=creationDate,desc&page=1&[email protected]&f_creationDate=creationDate:%5B2021-11-17T03:00:00.000Z%20TO%202021-11-18T02:59:59.999Z%5D -> orderBy=creationDate,desc&page=1&q=jemail=[email protected]&f_creationDate=creationDate:%5B2021-11-17T03:00:00.000Z%20TO%202021-11-18T02:59:59.999Z%5D)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.OMS().ListOrders({
filter : 'orderBy=creationDate,desc&page=1&[email protected]&f_creationDate=creationDate:%5B2021-11-17T03:00:00.000Z%20TO%202021-11-18T02:59:59.999Z%5D'
})
This method requires an object with one parameter:
- orderId (a string with the id from the order you want to load. Only not invoiced orders may be cancelled)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.OMS().CancelOrder({
orderId : '54353fsdf-01'
})
This method requires an object with one parameter:
- skuId (a number with the id from the SKU you want to load)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.Catalog().GetSKU({
skuId : 818
})
This method requires an object with one parameter:
- skuId (a number with the id from the product you want to load)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.Catalog().GetProduct({
productId : 213
})
This method requires an object with one parameter:
- refId (a string with the refId from the product you want to load)
vtex = new VTEX({
store : 'dummystore'
})
const searchResult = await vtex.Catalog().GetProductByRefId({
refId : 213
})
This method requires an object with one parameter:
- orderformId (a string with the id from the orderform object you want to load)
vtex = new VTEX({
store : 'dummystore'
})
const orderForm = await vtex.Checkout().LoadOrderformById({
orderformId : 'hgcfgtr456yhef'
})
This method requires an object with the following parameters:
- value (a number with the value that will be added to the giftcard)
- profileId (optional - client email or id. If an account is found with this email, the VTEX API will automatically look for the client's document. If this parameter is not passed, the voucher will be created with a fake address)
- multipleCredits (optional bool (default: false) - Defines if the giftcard balance can be changed)
- multipleRedemptions (optional bool (default: false) - Defines if the giftcard can be used to make new purchases until its value is completely used)
- restrictedToOwner (optional bool (default: false) - Defines if the giftcard can only be used for a specified client's id/email)
- caption (optional string (default: 'Giftcard') - Giftcard's caption)
- expiringDate (optional date (default: 9999-12-31T23:59:59.100Z) - Defines the giftcard's expiring date)
It returns the giftcard's redemption code.
vtex = new VTEX({
store : 'dummystore'
})
const giftcard = await vtex.Giftcard().CreateGiftcard({
value : 1
})
This method requires a object with the following parameter:
- id (this is the "lockId" wich can be found among the order details using the 'loadOrder' method)
vtex = new VTEX({
store : 'dummystore'
})
const reservation = await vtex.Logistics().ListReservationById({
id : '00-1234567890-01'
})
If you want add filters to the request or list a specific subscription, you'll have to pass the 'rule' parameter. If the rule parameters is not passed, the method will return the first page of subscriptions (limited by 15 lines by default).
vtex = new VTEX({
store : 'dummystore'
})
const subs = await Subscriptions().List({
rule : 'customerEmail=test%40test.com&page=1&size=15'
})
This module is intended for any sort of tools (third party or not) that might be hepful when using vtex-tools.
This a very simple implementation of the well known npm module https://www.npmjs.com/package/uuid Good for using as unique ids in master data's entities, cache and session identifying.
vtex = new VTEX({
store : 'dummystore'
})
//default V4
vtex.Utils().uuid()
//'1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
//using V1
vtex.Utils().uuid(1)
//'2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d'
These are the default values when you instanciate the module:
{
appKey : "APP_KEY",
appToken : "APP_TOKEN",
store : null, /*required*/
env : "vtexcommercestable.com.br"
}
You can easily overwrite them:
vtex = new VTEX({
store : 'dummystore',
appKey : 'STORE_KEY',
appToken : 'STORE_TOKEN',
})
REMEMBER: appKey AND appToken SHOULD NOT BE FILLED WITH YOUR CREDENTIALS, BUT WITH THE NAMES OF THE ENVIROMENT VARIABLES THAT CONTAIN THEM.
If you really need to provide the credentials directly to the contructor, say from a query result, you can do this using the following snippet:
vtex = new VTEX({
store : 'dummystore',
appKey : 'vtexappkey-dummiestore-ABCDEF', //the real key
appToken : 'REWREWRW5435435REWREW432RWFSGFDYTR543TGEGFDFDSREWr34TREGFDGDGDWSADWEFDSDFDSAFSADEFGEFD', //the real token
credentials: true
})
Aways wrapp the request inside a try catch. The module will throw an error that will break the execution if something goes wrong with the request.
Fell free to improve this module. Pull requests will be welcome. Just try to keep the existing structure.
Thanks