strapi-plugin-vtex

🚀 Overview

This plugin implements a complete purchase flow using the VTEX API, just install it and configure the environment variables to make the resources available for your front-end consume.

⏳ Installation

With npm:

npm install strapi-plugin-vtex

With yarn:

yarn add strapi-plugin-vtex

📦 Configuration

This plugin needs some environment variables to work, its variables is decribed on .env.example file but i going to describe it below too.

In particular, I prefer to configure and use plugin variables directly from the procces.env command instead of configuring them in the config/plugins.js file of the strapi project. I do not find it interesting to configure plugins outside the context of the plugin.

So the only thing you need to do is describe this environment variables on your .env file for development environment and setup the same variables on your server for production environment.

VTEX_API_PREFIX=true
VTEX_SCOPE=<yours-vtex-store-scope>
VTEX_API_KEY=<yours-vtex-api-key>
VTEX_API_SECRET=<yours-vtex-api-secret>
VTEX_TRADE_POLICY=<yours-vtex-trade-policy>
FACEBOOK_APP_KEY=<yours-facebook-app-key>
FACEBOOK_APP_SECRET=<yours-facebook-app-secret>
GOOGLE_APP_KEY=<yours-google-app-key>
GOOGLE_APP_SECRET=<yours-google-app-secret>

Describing each variable:

VTEX_API_PREFIX: (true) by default. With this flag, the plugin forces /vtex prefix to url api on all plugin routes, but you can disable it turning it to false, so your resources can look like (GET /vtex/me) or (GET /me) avoiding broken your other strapi implementations.

VTEX_SCOPE: Is your vtex subdomain commerce scope, it is used to identify your store on VTEX API PLATFORM.

VTEX_API_KEY: Is the generated API KEY used to get access to VTEX API PLATFORM.
(See this link tutorial to generate your access keys)

VTEX_API_SECRET: Is the generated API SECRET used to get access to VTEX API PLATFORM.
(See this link tutorial to generate your access keys)

VTEX_TRADE_POLICY: Is the configured trade policy in your VTEX PANEL to access your products and trade policies trought this plugin integration.

FACEBOOK_APP_KEY: Is the generated facebook app key configured in yours VTEX PANEL to able social login with facebook.

FACEBOOK_APP_SECRET: Is the generated facebook app secret configured in yours VTEX PANEL to able social login with facebook.

GOOGLE_APP_KEY: Is the generated google app key configured in yours VTEX PANEL to able social login with google.

GOOGLE_APP_SECRET: Is the generated google app secret configured in yours VTEX PANEL to able social login with google.

✨ API Resources

POST /auth/register
Create a customer account on VTEX PLATFORM [public]

{
	"email": "john.doe@gmail.com",
	"firstName": "John",
	"lastName": "Doe",
	"document": "11111111191",
	"phone": "+551199999999",
	"isNewsletterOptIn": true|false
}

POST /auth/request_reset
Request a reset password to desired vtex account email [public]

{
    "email": "john.doe@gmail.com"
}

POST /auth/reset
Reset password for desired vtex account email [public]

{
    "email": "john.doe@gmail.com",
    "authenticationToken": "F2D9E877E061A7C2AF70990B54EEC408829B523F9E094C8B4BB1018CB9C0AA38",
    "newPassword": "super-secret-password",
    "accessKey": "123456"
}

POST /auth/login
Execute the classic login (username & password) for VTEX customer account [public]

{
    "email": "john.doe@gmail.com",
    "password": "super-secret-password"
}

POST /me
Update authenticated VTEX customer account [protected by jwt token]

{
    "email": "john.doe@gmail.com",
    "password": "super-secret-password"
}

GET /me
Get authenticated VTEX customer account data [protected by jwt token]

GET /me/addresses
Get authenticated VTEX customer address data [protected by jwt token]

GET /me/addresses/:id
Fin one authenticated VTEX customer address [protected by jwt token]

POST /me/addresses
Create authenticated VTEX customer address [protected by jwt token]

{
    "addressName": "home",
    "addressType": "residential",
    "receiverName": "JOHN DOE",
    "postalCode": "943062700",
    "street": "Solana Dr",
    "number": "404",
    "complement": "B",
    "neighborhood": "Barron Park",
    "city": "Palo Alto",
    "state": "CA",
    "country": "USA",
    "geoCoordinate": [0, 0],
    "reference": null
}

PUT /me/addresses/:id
Update authenticated VTEX customer address [protected by jwt token]

{
    "addressName": "newhome",
    "addressType": "residential",
    "receiverName": "JOHN DOE",
    "postalCode": "943062700",
    "street": "Solana Dr",
    "number": "404",
    "complement": "B",
    "neighborhood": "Barron Park",
    "city": "Palo Alto",
    "state": "CA",
    "country": "USA",
    "geoCoordinate": [0, 0],
    "reference": null,
    "reference": "close to school"
}

DELETE /me/addresses/:id
Delete an authenticated VTEX customer address [protected by jwt token]

GET /categories/level/:level
Retrieve all categories from VTEX PLATFORM with cascade levels [public]

GET /stores
Retrieve all registeres physic stores from VTEX PLATFORM [public]

GET /collections
Retrieve all collections from VTEX PLATFORM [public]

GET /collections/:id/products
Retrieve products from VTEX PLATFORM for a specific collection [public]

GET /products/autocomplete?searchTerm=Cellphone
Retrieve product suggestions from VTEX PLATFORM for input searchTerm [public]

GET /products
Retrieve a list of products from VTEX PLATFORM [public]

GET /orders
Retrieve a list of orders from VTEX PLATFORM authenticated customer [protected by jwt token]

GET /orders/:id
Retrieve a specific order from VTEX PLATFORM authenticated customer [protected by jwt token]

POST /orders/simulation
Simulate an order on VTEX PLATFORM to preview available subtotal, taxes, payment conditions and shipping methods [public]

{
	"items":[{
		"id":"12345",
		"quantity": 1,
		"seller": "1"
	}],
	"postalCode": "943062700",
	"country": "USA"
}

POST /orders
Generate an order on VTEX PLATFORM to specified clientProfileData.email, if user does not has an account yet, it will be generated for specified email, than you will be able to reset the password over the POST /auth/request_reset resource. [public]

{
	"items":[{
		"id":"12345",
		"quantity": 1,
		"seller": "1"
	}],
	"paymentSystem": 6,
	"installments": 1,
	"shippingMethod": "Fedex",
	"clientProfileData": {
		"email": "john.doe@gmail.com",
        "firstName": "John",
        "lastName": "Doe",
        "document": "11111111191",
        "phone": "+551199999999",
        "isNewsletterOptIn": true|false
	},
	"cc": {
		"holderName": "JOHN DOE",
        "cardNumber": "4111111111111111",
		"dueDate": "09/24",
		"validationCode": "123"
	},
	"address":{
		"addressName": "home",
        "addressType": "residential",
        "receiverName": "JOHN DOE",
        "postalCode": "943062700",
        "street": "Solana Dr",
        "number": "404",
        "complement": "B",
        "neighborhood": "Barron Park",
        "city": "Palo Alto",
        "state": "CA",
        "country": "USA",
        "geoCoordinate": [0, 0],
        "reference": null
	}
}

GET /locations/cep/:cep
Retrieve address suggestion for specified zipcode [brazil only] [public]

GET /locations/estados
Retrieve a list of states in brazil [brazil only] [public]

GET /locations/estados/:uf/municipios
Retrieve a list of cities for specified state in brazil [brazil only] [public]

GET /locations/municipios/:city/bairros
Retrieve a list of neighborhoos for specified city in brazil [brazil only] [public]

🎉 Congradulations, You're done.

With this plugin you will be able to expose all vtex purchase flow to your front-end applications and create new great features for them with strapi, of corse.

📜 License

This project is under the MIT license. See the LICENSE for details.

💻 Developed by André Ciornavei - Get in touch!