Guia de integração

Através deste guia você conseguirá as informações necessárias para conectar sua aplicação à plataforma de e-commerce da BW. Por meio da integração, você poderá enviar seus produtos, estoques, preços, hierarquias, baixar clientes, pedidos, entre outros.

Para facilitar, este guia está dividido em algumas seções. São elas:

• Introdução
• Obtendo um ambiente
• Autenticação
• Retorno padrão
• Estruturas de dados
• Fluxo de integração
• Upload de arquivo

Introdução

A integração entre sua aplicação e a plataforma de e-commerce da BW é feita através de um web service. Esse web service foi criado seguindo o estilo arquitetural REST. Ou seja, de forma resumida, sua aplicação deverá fazer requisições para nossa API REST utilizando o protocolo HTTP.

Para fazer estas requisições HTTP, existem bibliotecas para as mais diversas linguagens de programação. Alguns exemplos estão listados abaixo:

• Guzzle, para PHP
• Unirest, para Java
• RestSharp, para C#
• Pacote HTTP, para Node.js
• Net::HTTP, para Ruby
• Requests, para Python
• Pacote http, para GO
• TNetHTTPClient, para Delphi

A partir do uso dessas bibliotecas (ou de outras de acordo com sua escolha e necessidade), você poderá disparar requisições HTTP que farão o envio dos dados da sua aplicação para nossa API, a qual encaminhará os dados para os bancos de dados da plataforma de e-commerce da BW.

O cenário mais comum é obter as informações no banco de dados da sua aplicação, converter essas informações de acordo com as nossas estruturas de dados (veja a seção 5, ela fala sobre as estruturas de dados mais detalhadamente), fazer o envio dessas informações convertidas através de requisições HTTP e obter seu retorno.

Obtendo um ambiente

Se você ainda não possui um ambiente para iniciar o desenvolvimento da conexão entre sua aplicação e nossa plataforma de e-commerce, você deverá enviar um e-mail para nossa equipe através deste endereço de e-mail. O assunto do da mensagem de e-mail deve ser “Nome da sua empresa # Integração API”.

Após isso, nossa equipe irá criar um ambiente de testes e você receberá as informações necessárias (endpoint da API REST, usuário e senha) para poder iniciar o desenvolvimento e os testes da conexão da sua aplicação com nossa plataforma de e-commerce.

Autenticação

Como já mencionado, nosso web service é uma API REST acessada por requisições utilizando o protocolo HTTP. Sendo assim, a API não é capaz de guardar estados, consequentemente, é necessário que em toda requisição performada seja feita a autenticação novamente.

Para fazer a autenticação em nossa API REST, você precisará ter seu login e sua senha. Esses dados serão passados à você pela nossa equipe quando o ambiente de testes for liberado (veja a seção 2, ela fala sobre a obtenção de um ambiente de testes). De forma resumida, você precisará codificar seu usuário e sua senha, separando-os por dois pontos (:) e enviar em um cabeçalho da requisição chamado Authorization. Veja o exemplo abaixo utilizando a linguagem de programação PHP.

				
// Suas credenciais da API
				$usuario = 
'integracao'
;
				$senha = 
'123456'
;

				
// Gera o conteúdo codificado (seu usuário:sua senha)
				$usuarioSenhaCodificados = 
base64_encode
(
sprintf
(
'%s:%s'
, $usuario, $senha));

				
// Adiciona o prefixo Basic ao cabeçalho
				$cabecalhoAuthorization = 
sprintf
(
'Basic %s'
, $usuarioSenhaCodificados);

				
// Saída: Basic aW50ZWdyYWNhbzoxMjM0NTY=
				
echo
 $cabecalhoAuthorization . PHP_EOL;
			

Utilize este valor gerado como cabeçalho Authorization na hora de fazer a requisição HTTP. Essa implementação (definir o cabeçalho) vai depender da sua linguagem de programação e cliente HTTP utilizado.

Retorno padrão

A API de integração trabalha com o formato JSON tanto para o recebimento quanto para o retorno de dados.

Além disso, possui uma estrutura de dados padrão para o retorno. Todas as requisições retornarão os dados na seguinte estrutura de dados. A estrutura de dados está detalhada na tabela abaixo.

Dito isso, o objeto JSON retornado pela API é semelhante ao mostrado abaixo.

				{
				
"registros"
: [],
				
"erros"
: [],
				
"dataHoraServidor"
: 
"0001-01-01 00:00:00"
,
				
"totalRegistros"
: 
1000
,
				
"totalRegistrosPaginaAtual"
: 
100
,
				
"totalPaginas"
: 
10
,
				
"limitePagina"
: 
100
				}
			

Estruturas de dados

Para tornar possível a troca de informações entre a sua aplicação e a plataforma de e-commerce da BW, é necessário que hajam estruturas de dados pré-definidas para cada recurso da API (ou entidade, por exemplo “cliente” é um recurso).

Essa estrutura de dados é composta por vários atributos/propriedades/campos que possuem seu próprio tipo de dados. Essa estrutura de dados pré-definida deve ser respeitada tanto na hora de enviar dados quanto na hora de receber dados.

Para visualizar essas estruturas de dados e também como acessá-las, você deverá acessar esta página. Nela você encontrará: como acessar (URL/rota) os recursos e como ele é composto (estrutura de dados) (nome dos atributos, tipo de dado dos atributos, obrigatoriedade dos atributos, etc). Além disso, poderá visualizar qual método HTTP deve ser utilizado na hora de acessar o recurso e também alguns exemplos do retorno que é devolvido pelo recurso em questão.

Uma observação importante é que todos os campos (de envio e de retorno) da API são case sensitive, então preste bastante atenção na hora em que for implementar o código da integração. Outro detalhe é: campos que estão na seção “BW Commerce” da documentação de estruturas de dados nunca são obrigatórios, pois eles não tem ligação com a integração com a plataforma de e-commerce.

Fluxo de integração

Para que sua integração seja realmente funcional, precisamos garantir que algumas implementações sejam feitas de acordo com nossas regras de negócio. Para tornar isso transparente ao parceiro que está implementando a integração entre sua aplicação e a plataforma de e-commerce da BW, existe um fluxo padrão que deve ser respeitado.

No fluxograma abaixo, é possível visualizar o fluxo de integração. Alguns recursos são obrigatórios e devem ser implementados. Já outros recursos são opcionais e vão depender das informações que você possui (ou não possui) em sua aplicação.

Sendo assim, observamos que para cada recurso possuímos uma obrigatoriedade: obrigatório (indicado pela cor vermelha), opcional (indicado pela cor azul) e opcional, mas recomendado (indicado pela cor verde).

Os recursos obrigatórios a serem integrados são:

• Hierarquias
• Produtos
• Lista de produto
• Valores
• Clientes
• Endereços de clientes
• Pedidos
• Itens de pedidos

Os recursos opcionais, mas recomendados, a serem integrados são:

• Marcas
• Upload
• Imagens

Os recursos opcionais a serem integrados são:

• Unidades de medida
• Cores
• Tamanhos
• Materiais
• Variações
• Listas de cliente
• Características
• Filtros
• Itens de filtros
• Filtros de produtos,
• Produtos vinculados
• Produtos compre junto
• Embalagens
• Produtos embalagens
• Destaques
• Transportadoras

Se você observar, verá que alguns recursos exibidos na documentação das estruturas de dados não estão listados aqui. Isso é porque: ou eles foram depreciados, ou não são relacionados a plataforma de e-commerce em si.

Para que sua integração seja realmente funcional, precisamos garantir que algumas implementações sejam feitas de acordo com nossas regras de negócio. Para tornar isso transparente ao parceiro que está implementando a integração entre sua aplicação e o aplicativo de força de vendas da BW, existe um fluxo padrão que deve ser respeitado.

No fluxograma abaixo, é possível visualizar o fluxo de integração. Alguns recursos são obrigatórios e devem ser implementados. Já outros recursos são opcionais e vão depender das informações que você possui (ou não possui) em sua aplicação.

Sendo assim, observamos que para cada recurso possuímos uma obrigatoriedade: obrigatório (indicado pela cor vermelha), opcional (indicado pela cor azul) e opcional, mas recomendado (indicado pela cor verde).

Os recursos obrigatórios a serem integrados são:

• Hierarquias
• Produtos
• Lista de produto
• Valores
• Clientes
• Vínculo entre cliente e vendedor
• Endereços de clientes
• Pedidos
• Itens de pedidos

Os recursos opcionais, mas recomendados, a serem integrados são:

• Marcas
• Upload
• Imagens
• Formas de pagamento
• Condições de pagamento
• Tipos de pedido

Os recursos opcionais a serem integrados são:

• Unidades de medida
• Cores
• Tamanhos
• Materiais
• Variações
• Listas de cliente
• Características
• Filtros
• Itens de filtros
• Filtros de produtos,
• Produtos vinculados
• Produtos compre junto
• Embalagens
• Produtos embalagens
• Destaques
• Formas - condições de pagamento
• Tipos de pedido - condições de pagamento
• Transportadoras

Upload de arquivo

É bastante comum que você possua imagens cadastradas em sua aplicação. Imagens principalmente referentes aos produtos que o cliente possui. É possível fazer o envio dessas imagens através da API de integração.

Para isso você precisará utilizar este método. Através dele você pode definir três informações principais: o nome da pasta (no caso dos produtos, o nome da pasta será “produtos”), o nome do arquivo, o conteúdo do arquivo codificado em base64.

Além disso, através da propriedade “excluir”, você poderá excluir um arquivo antigo, o qual será substituído pelo arquivo que você está enviando no momento.