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": "[email protected]",
	"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": "[email protected]"
}

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

{
    "email": "[email protected]",
    "authenticationToken": "F2D9E877E061A7C2AF70990B54EEC408829B523F9E094C8B4BB1018CB9C0AA38",
    "newPassword": "super-secret-password",
    "accessKey": "123456"
}

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

{
    "email": "[email protected]",
    "password": "super-secret-password"
}

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

{
    "email": "[email protected]",
    "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": "[email protected]",
        "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!