API - BigDataEcommerce

A API do BigDataEcommerce foi criada para que facilite a interação com qualquer linguagem ou plataforma. Sabemos da importância de uma API para que aplicativos possam se integrar com as nossas ferramentas, produtos e serviços. A API está disponivel somente via HTTP (sugira outras formas de integração). A URL base é http://dominio_ecommerce/api/
Todos os dados devem ser recebidos através de uma requisição GET tendo em um único parâmetro
request um JSON estruturado e encriptado em Base64 contendo a autenticação, a solicitação e a informação desejada, recebendo como retorno um JSON limpo em formato texto.

Esta API tem por finalidade facilitar a integração entre a aplicação do cliente e o serviço BigDataEcommerce, de forma a atualizar e consultar informações relacionadas aos produtos e as vendas realizadas pelo e-commerce do cliente.

O consumo de recursos da API se dá através de chamadas HTTP urtilizando método GET e recebendo retornos em JSON que devem ser tratados no lado da aplicação que esta consumindo a API.

As chamadas devem ser realizadas através da URL do e-commerce a ser consultado, acresdido de: "api/api.php", passando apenas um único parametro, chamado de request, que em seu conteúdo deve transmitir um JSON encriptado em Base64, contendo enfim os parâmetros estruturados para autenticação e consumo dos métodos internos da API, entre eles, a *key* (chave) de autencitação, o *action* (ação) e *info* (informação) a ser trabalhada pela API.

Para fins didáticos utilizaremos aqui a loja de demonstração como base para os testes deste manual.

Parametro	Conteúdo
	Formação da Requisição
URL	http://url_instalacao_ecommerce.com.br http://store.bigdataecommerce.com.br
Path	/api
API	/api.php
GET	?request
Parametros em JSON	{"key":"MD5_do_APIUser_da_loja","action":"ação_a_ser_realizada","info":"informação_complementar_a_ação"} {"key":"1d87c5c60bd9e489ec710a0db20ca46b","action":"validate","info":"key"} Verificar
Parametros em JSON Encriptados em Base64	eyJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiIsImFjdGlvbiI6InZhbGlkYXRlIiwiaW5mbyI6InZhbGlkYXRlIn0= Verificar
Chave de 256 do APIUser	WqtTQTgEaiWA427pNJ8u0iZnd8hi78JiGpXA31kBMIGVwZTyw145s50BlVyGuUWTwPguftxFFdtLYD237aOEIitpDQzLZE4DYgGdaMvMSYqCSnHIZHFpKIoxRDcadkZWqlSZRMhC3uUbqJdztisoosMkob4EJREo08vLLadEexIkd2ExwbP2a0Gy3IE7KmoDGYJcRZPzdnyRnMdSi0hr5LgFhpFopU0cfhj1hODRLl6ewpVxBMLR5AsIZPChHvey Verificar OBS:A chave pode ser obtida no backoffice da loja em: Configurações -> Gerenciar usuários -> API
MD5 da Chave de 256 do APIUser	1d87c5c60bd9e489ec710a0db20ca46b
	Requisição
Formação da URL	http://url_instalacao_ecommerce/api/api.php?request=JSON_encriptado_em_Base64 http://store.bigdataecommerce.com.br/api/api.php?request=eyJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiIsImFjdGlvbiI6InZhbGlkYXRlIiwiaW5mbyI6ImtleSJ9 Verificar

	Retorno
Exemplo de resposta recebida:	{"Status":"OK","Message":"Chave v\u00e1lida!"}

Observações:

Todas as chamadas (requisições) devem conter um único JSON obedecendo o seguinte padrão no request:

Exemplo de formação da URL de requisição: http://dominio_ecommerce/api/api.php?request=JSON_encriptado_em_Base64
Exemplo de resposta recebida: {"Status":"OK","Message":"Produtos com estoque ou pre\u00e7o zerado desativados com sucesso!"}
* IMPORTANTE: O parametro KEY (chave) é formado pelo MD5 da chave de 256 caracteres associada ao usuário chamado APIUser. Esta chave de 256 caracteres deve ser gerada no backoffice da loja virtual em: Configurações -> Gerenciar usuários -> API

Troque http://store.bigdataecommerce.com.br pela URL da instalação de seu e-commerce.

JavaScript Jquery

Para gerar o MD5 da chave do usuário APIUSer podemos utilizar a biblioteca: https://github.com/placemarker/jQuery-MD5

	var keyAPIUser = 'WqtTQTgEaiWA427pNJ8u0iZnd8hi78JiGpXA31kBMIGVwZTyw145s50BlVyGuUWTwPguftxFFdtLYD237aOEIitpDQzLZE4DYgGdaMvMSYqCSnHIZHFpKIoxRDcadkZWqlSZRMhC3uUbqJdztisoosMkob4EJREo08vLLadEexIkd2ExwbP2a0Gy3IE7KmoDGYJcRZPzdnyRnMdSi0hr5LgFhpFopU0cfhj1hODRLl6ewpVxBMLR5AsIZPChHvey';
	var MD5KeyAPIUser = $.md5(MD5KeyAPIUser).toString();
	console.log('MD5 da Chave do APIUSer: ' + MD5KeyAPIUser);

Para gerar o conteúdo do request da URL e consumir a API, devemos encriptar o JSON de requisição em Base64

	var JsonParameters = {"key":"1d87c5c60bd9e489ec710a0db20ca46b","action":"validate","info":"validate"};
	var requestBase64 = btoa(JSON.stringify(JsonParameters));
	console.log('Valor do parametro request:' + requestBase64);

Para consumir a API da loja (neste exemplo a sandbox) instalada em http://store.bigdataecommerce.com.br, podemos utilizar o seguinte código:

	var requestAPI = "http://store.bigdataecommerce.com.br/api/api.php?request=eyJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiIsImFjdGlvbiI6InZhbGlkYXRlIiwiaW5mbyI6ImtleSJ9";
	$.ajax({
	   type: 'GET',
	   crossDomain: true,
	   dataType: 'json',
	   url: requestAPI,
	   success: function(result){
			alert("Status: " + result.Status + " - Message: " + result.Message);
	   }
	})

PHP

Consumo da API

	$url = "http://store.bigdataecommerce.com.br/api/api.php?request=eyJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiIsImFjdGlvbiI6InZhbGlkYXRlIiwiaW5mbyI6ImtleSJ9";
	$response = file_get_contents($url);

Para fins de economia de banda e dinamizar os acessos de consumo à API, e de modo a permitir consultas em um limite de tempo não determinado, não são geradas sessões, consumo por autenticidade através de uma chave de acesso que é associada ao usuário APIUser, que por sua vez pode ser registrado, ativado e desativado, bem como, ter a sua chave gerada ou modificada no backoffice do e-commerce em:

Configurações -> Gerenciar usuários -> API

Esta chave possui 256 caracteres, porém, a chave a ser empregada e transportada junto a todas as requisições de consumo da API é uma chave de apenas 32 caracteres, formada por sua vez pela HASH MD5 da chave gerada pelo e-commerce para o usuário APIUser.

Para poder utilizar (consumir) e testar a API, primeiramente você deve cadastrar ou ativar o usuário APIUser gerando para o mesmo uma nova chave de 256 caracteres.

Autenticação via chave de acesso (token) é ideal para segurança.

action	info	outros valores do JSON	Descrição
insert	category	codigo = Código da categoria name = Descrição da categoria	Insere uma nova categoria *JSON para inserção ou atualização de uma nova categoria, departamento ou grupo:* {"action":"insert","key":"1d87c5c60bd9e489ec710a0db20ca46b","info":"category","codigo":"500","name":"PADARIA"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoiY2F0ZWdvcnkiLCJjb2RpZ28iOiI1MDAiLCJuYW1lIjoiUEFEQVJJQSIsImFjdGlvbiI6Imluc2VydCIsImtleSI6IjFkODdjNWM2MGJkOWU0ODllYzcxMGEwZGIyMGNhNDZiIn0A Retorno recebido: {"Status":"OK","Message":"Grupo [500] cadastrado ou atualizado com sucesso!"} Verificar
	subcategory	codigo = Código da subcategoria name = Descrição da subcategoria parent_id = Código da categoria principal	Insere uma nova subcategoria *JSON para inserção ou atualização de uma subcategoria, sub-departamento ou sub-grupo:* {"action":"insert","key":"1d87c5c60bd9e489ec710a0db20ca46b","info":"subcategory","codigo":"001","name":"sub grupo teste","parent_id":"001"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoic3ViY2F0ZWdvcnkiLCJjb2RpZ28iOiIwMDEiLCJuYW1lIjoic3ViIGdydXBvIHRlc3RlIiwicGFyZW50X2lkIjoiMDAxIiwiYWN0aW9uIjoiaW5zZXJ0Iiwia2V5IjoiMWQ4N2M1YzYwYmQ5ZTQ4OWVjNzEwYTBkYjIwY2E0NmIifQA Retorno recebido: {"Status":"OK","Message":"Grupo [1] cadastrado ou atualizado com sucesso!"} Verificar
	product	gtin = Código GTIN/EAN do produto name = Descrição do produto price = preço co produto / ####.## category_id = Código da categoria do produto parent_id = Código da categoria principal image = Será ativado apenas para configurar fotos já existentes na loja quantity = Quantidade do produto / #####	Insere ou atualiza os um determinado produto, caso o produto já exista, atualiza apenas o preço e a quantidade, desativando o mesmo caso a quantidade esteja zerada. * Consulte o guardiam e as bibliotecas de apoio para realizar o upload automático de fotos encontradas para o produto. *JSON para inserção ou atualização de produto:* {"key":"1d87c5c60bd9e489ec710a0db20ca46b","action":"insert","info":"product","gtin":"7896267103201","category_id":"13","price":"2.75","name":"SUCO PROMIX 150G CAJU","parent_id":"1","quantity":"12.500"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJxdWFudGl0eSI6IjEyLjUwMCIsImluZm8iOiJwcm9kdWN0IiwiZ3RpbiI6Ijc4OTYyNjcxMDMyMDEiLCJjYXRlZ29yeV9pZCI6IjEzIiwicHJpY2UiOiIyLjc1IiwibmFtZSI6IlNVQ08gUFJPTUlYIDE1MEcgQ0FKVSIsInBhcmVudF9pZCI6IjEiLCJhY3Rpb24iOiJpbnNlcnQiLCJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiJ9AA Retorno recebido: {"Status":"OK","Message":"Produto [26\/7896267103201] atualizado com sucesso!"} Verificar

validate	key		Verifica se a chave é válida *JSON para inserção ou atualização de produto:* {"info":"key","action":"validate","key":"1d87c5c60bd9e489ec710a0db20ca46b"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoia2V5IiwiYWN0aW9uIjoidmFsaWRhdGUiLCJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiJ9AA Retorno recebido: {"Status":"OK","Message":"Chave v\u00e1lida!"} Verificar

list	category EM PROCESSO DE EDIÇÃO		Retorna uma lista em texto simples contendo a lista as categorias e subcategorias cadastradas *JSON para recuperação da lista de categorias e sub-categorias cadastradas:* {"action":"list","info":"category","key":"1d87c5c60bd9e489ec710a0db20ca46b"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoiY2F0ZWdvcnkiLCJhY3Rpb24iOiJsaXN0Iiwia2V5IjoiMWQ4N2M1YzYwYmQ5ZTQ4OWVjNzEwYTBkYjIwY2E0NmIifQA Retorno recebido: {"seq_1":1,"parent_id_1":"0","name_1":"sub grupo teste","category_id_1":"1","category_1":"","top_1":"0","status_1":"1", ..., ..., ..., ..., "total":15} Verificar
	products EM PROCESSO DE EDIÇÃO		Retorna uma lista em texto simples contendo a lista os produtos cadastrados *JSON para recuperação da lista de categorias e sub-categorias cadastradas:* {"action":"list","info":"products","key":"1d87c5c60bd9e489ec710a0db20ca46b"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoicHJvZHVjdHMiLCJhY3Rpb24iOiJsaXN0Iiwia2V5IjoiMWQ4N2M1YzYwYmQ5ZTQ4OWVjNzEwYTBkYjIwY2E0NmIifQA Retorno recebido: {"seq_1":1,"product_id_1":"1","ean_1":"7891109789841","name_1":"SAND HAV COLOR AZUL NAVAL 41\/42 PAR","quantity_1":"9","image_1":"catalog\/produtos\/sand_hav_color\/7891109789841.jpg","price_1":"12.5000","points_1":"0","weight_1":"0.00000000","status_1":"1","viewed_1":"0", ..., ..., ..., ..., "total":5} Verificar
	sales	date = data da movimentação	Retorna uma lista em texto simples contendo a lista de vendas em uma determinada data *JSON para recuperação da lista de vendas de uma determinada data, neste exemplo: 11-05-2020:* {"action":"list","info":"sales","key":"1d87c5c60bd9e489ec710a0db20ca46b","date":"2020-05-11"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoic2FsZXMiLCJkYXRlIjoiMjAyMC0wNS0xMSIsImFjdGlvbiI6Imxpc3QiLCJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiJ9AA Retorno recebido: {"seq_1":1,"order_id_1":"35","customer_id_1":"1","order_status_name_1":"Anulado","name_1":"HALLS 27G CEREJA","email_1":"email@cliente.com","telephone_1":"(xx) xxxx-xxxxx","payment_method_1":"Pagar ao retirar na loja","total_1":"1.2500","shipping_method_1":"Retirar na loja","comment_1":"","payment_name_1":"NOME DO CLIENTE","payment_address_1":"","shipping_name_1":"NOME DO CLIENTE","shipping_address_1":"","itens_1_seq_1":1,"order_product_id_1":"474","product_id_1":"3957","ean_1":"7895800169230","model_1":"7895800169230","quantity_1":"1","price_1":"1.2500","total_1_itens":1,"seq_2":2,"order_id_2":"35","customer_id_2":"0","order_status_name_2":"Anulado","name_2":"LEITE LIQ ITALAC 1L INTEGRAL","email_2":"romerio@gmail.com","telephone_2":"","payment_method_2":"","total_2":"3.9900","shipping_method_2":"","comment_2":"","payment_name_2":" ","payment_address_2":"","shipping_name_2":" ","shipping_address_2":"","itens_2_seq_1":1,"itens_2_seq_2":2,"order_product_id_2":"475","product_id_2":"14740","ean_2":"7898080640611","model_2":"7898080640611","quantity_2":"1","price_2":"3.9900","total_2_itens":2,"total":2} Verificar
	noimage		Retorna uma lista em texto simples contendo a relação de produtos sem imagem de rosto definida *JSON para recuperação da lista de produtos sem foto de rosto:* {"info":"noimage","action":"list","key":"1d87c5c60bd9e489ec710a0db20ca46b"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoibm9pbWFnZSIsImFjdGlvbiI6Imxpc3QiLCJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiJ9AA Retorno recebido: product_id\|ean\|description\|RELAÇÃO DE PRODUTOS SEM IMAGEM: [5] 2\|574\|APONTADOR SIMPLES\|1 3\|7896910000109\|ARROZ STAACK 1 KG\|2 ... ... 9\|7891151028400\|FREEGELLS AZEDINHO UVA\|5 Verificar

manager	disablefromstock		Desativa os produtos que estiverem com estoque ou preço zerado *JSON para desativação de produtos com estoque ou preço zerados:* {"action":"manager","info":"disablefromstock","key":"1d87c5c60bd9e489ec710a0db20ca46b"} JSON convertido para Base64, pronto para ser adicionado à requisição e consumido: eyJpbmZvIjoiZGlzYWJsZWZyb21zdG9jayIsImFjdGlvbiI6Im1hbmFnZXIiLCJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiJ9AA Retorno recebido: {"Status":"OK","Message":"Produtos com estoque ou pre\u00e7o zerado desativados com sucesso!"} DESATIVAR

Wizard de parametros

API - BigDataEcommerce!

Conhecendo a API BigDataEcommerce

{"key":"1d87c5c60bd9e489ec710a0db20ca46b","action":"validate","info":"key"}

Verificar

eyJrZXkiOiIxZDg3YzVjNjBiZDllNDg5ZWM3MTBhMGRiMjBjYTQ2YiIsImFjdGlvbiI6InZhbGlkYXRlIiwiaW5mbyI6InZhbGlkYXRlIn0=

Verificar

Verificar

Verificar