Manual de integração com Marketplaces e E-Commerce

O B2W Marketplace é um hub de vendas que permite que você crie sua loja e exponha seus produtos dentro de alguns dos maiores e-commerces do país como Americanas.com, Submarino e Shoptime.

Já a SkyHub, é a porta de entrada para os principais marketplaces do Brasil. Mais especificamente a Skyhub é o hub de integração com os marketplaces pertencentes as B2W.

A Skyhub disponibiliza um conjunto de APIs para que você se preocupe apenas em cuidar da integração do seu ERP ou de sua plataforma, de maneira que qualquer mudança nas APIs dos marketplaces que implique em mudança para os sistemas integrados fiquem sobre a responsabilidade da SkyHub.

VPN (Virtual Private Network) é uma rede privada virtual, na qual as informações de uma rede local são passadas por um túnel, em uma rede publica qualquer.
Iremos utilizar a VPN para nos conectarmos com o repositório onde os nossos códigos estão publicados e também para que possamos acompanhar os processos referentes a publicação de produtos e pedidos que são gravados no Banco de Dados.

GitHub é uma plataforma de hospedagem de código-fonte com controle de versão usando o Git. Ele permite que programadores, utilitários ou qualquer usuário cadastrado na plataforma contribuam em projetos privados e/ou Open Source de qualquer lugar do mundo. 

AUTENTICAÇÃO

Todas as chamadas aos serviços disponíveis na SkyHub devem ser autenticadas a partir do e-mail do usuário, token de acesso e accountmanager. Essas informações devem ser enviados no cabeçalho (header) de cada requisição.

INTEGRAÇÃO

A integração completa realizada entre o Omni/Moddo-Channels e a Skyhub considera que sejam atendidas as operações abaixo:

Produtos

• Criar
• Atualizar
• Deletar

Pedidos

• Criar
• Atualizar
• Consumir

JET é um conector que integra através da geração de token, usando credenciais e chamadas via post, que permite que você crie pedidos e categorias de produtos.

Exemplo ao inserir uma nova categoria

Campo "level"

Ao inserir uma nova categoria, o campo level será usado para indicar qual a categoria superior.

Os valores aceitos serão:
"" - Vazio
Nesse caso, a categoria será cadastrada sem categoria superior, sendo considerada uma categoria inicial da hierarquia.

"01" - Valores no padrão de código de nível da categoria superior.
Esses valores indicam qual deverá ser considerada a categoria superior na hierarquia. Se o valor informado no campo level for 01, indica que a categoria será cadastrada como sendo uma subcategoria, tendo sua categoria pai a que possui o código 01 no nível.
Você consegue obter o valor do nivel da categoria, utilizando o método GetLevel da nossa API.

No exemplo acima, vamos usar a categoria "Moda Masculina" que possua o código do level igual a "01". Ao cadastrar uma nova categoria "Camisetas" que seja filha da categoria "Moda Masculina", ao final do cadastro, a hierarquia ficará da seguinte maneira:

01 - Moda Masculina

0101 - Camiseta

010101 - Algodão

...

Os valores de categoria vão de 01 a 99. Ou seja, será possível cadastrar até 99 categorias com 3 níveis de hierarquia de subcategoria.

É um Marketingplace de venda que permite acessar aos recursos de integração com a Magalu. utilizamos a API da Magalu via Rest Service

O conector Magento, assim como outros conectores, possui configurações que devem ser realizadas no nível da credencial.

Os pedidos são baixados para o Omni desde que estejam com o status presente em um campo da credencial chamado MAGENTO_ESTADOS_PEDIDOS_PAGADOS, normalmente configurado com o valor complete

O TOTVS Omni baixa somente os pedidos do dia. Esta restrição não está parametrizada na credencial.

Isto deve-se à restrições de performance e volumetria que pode ocorrer com pedidos muitos antigos, e há uma configuração para baixar pedidos do dia.

Dados importantes de serem configurados na credential:

MAGENTO_ESTADOS_PEDIDOS_PAGADOS: complete

MAGENTO_HOST: http://177.125.218.245/

MAGENTO_ID_WEB_sITE: 1

MAGENTO_PASSWORD: kzPJ0oEEdQyW

MAGENTO_STORE_CODE: default

MAGENTO_USERNAME: magentohomo

magento.order.customer.fiscal.id: customer_cpf

magento.order.store.id: loja_retirada_id

MAIL TO: [email protected]

Para que o Omni possa continuar o processo de seleção do operador logístico é necessário que o conector baixe pedidos do Magento com o nível de serviço selecionado pelo cliente.

A API de integração da Via Varejo permite que lojistas comercializem seus produtos no Marketplace Via Varejo através de uma interface. Através dela é possível cadastrar produtos, gerenciar os estoques e preços e ser notificado quando pedidos são feitos e confirmados.

Mapeamento de criação de pedidos Via Varejo

Observações:

Status dos pedidos.

Status de tracking dos pedidos.

Código de Pagamento.

Separação dos campos rua, número e complemento para endereços sender e shipping

O conector do VTEX permite trabalhar a integração com o TOTVS Omni em dois formatos: Com Franquias ou Sem Franquias.

No cenário de franquia cada loja pode ser vista como se fosse uma instancia de VTEX separada. E para que o Omni possa se comunicar necessita de credencias de acesso próprias.

De forma resumida, o conector funciona publicando produtos no VTEX e carregando o stock atrelado a cada loja (ou seller, como são chamadas as lojas no VTEX).

Uma vez realizada a compra no VTEX, o pedido criado é associado à um desses sellers de acordo com a forma de entrega escolhida pelo usuário.

O TOTVS Omni, ao descer os pedidos, obedece à esta decisão de submissão de pedido à seller do VTEX, sendo assim, o conector cria o pedido no Omni já com a identificação de qual loja irá atender o pedido (ID_ALMACEN_SUMINISTRADOR).

Abaixo vemos dois exemplos de JSON de pedidos do VTEX: O primeiro de loja principal e o segundo de franquia.

A diferença dar-se no prefixo do pedido, que inicia com SLR.

Pedido de loja principal:
JSON Pedido Expandir origem

Pedido de Franquia:
JSON Expandir origem

Configurar o conector do Mercado Livre:

Parar configurar o conector do Mercado Livre, o cliente precisa criar uma conta para TOTVS com perfil administrador e logar com essa conta TOTVS em https://developers.mercadolivre.com.br

• Acessar Avatar > Minhas Aplicações, criar uma applicacao e copiar o ID (APP_ID)
  Configurar a appi:
• Acesso a todas APIs: Marcar todos
  URI de redirect: https://co.moddoplataform.com/marketplace/ml/redirect
  URL de retornos de chamada de notificação: https://co.moddoplataform.com/marketplace/ml/notifications
• O cliente deve Editar a aplicação e anotar o Secret Key, após isso, chamar no browser a URL:
  http://auth.mercadolivre.com.br/authorization?response_type=code&client_id=405024317153660&redirect_uri=https://co.moddoplataform.com/marketplace/ml/redirect

Substituindo APP_ID com o ID da App criada.

• Na tela de autorizar conexão clique em permitir. O browser vai tentar chamar a URL:
  https://co.moddoplataform.com/marketplace/ml/redirect?code=AUTHORIZATION_CODE
• Anotar o AUTHORIZATION_CODE
• Utilizar o postman ou curl para trocar o authorization_code por um acess_token:

curl -X POST -H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
'https://api.mercadolibre.com/oauth/token' \
-d 'grant_type=authorization_code' \
-d 'client_id=APP_ID' \
-d 'client_secret=SECRET_KEY' \
-d 'code=AUTHORIZATION_CODE' \
-d 'redirect_uri=https://co.moddoplataform.com/marketplace/ml/redirect'

Substituindo os valores correspondentes a APP_ID, SECRET_KEY e AUTHORIZATION_CODE.

• Anotar o access tooken da resposta da chamada acima
  Ex:
  {
  "access_token": "APP_USR-123456-090515-8cc4448aac10d5105474e1351-1234567",
  "token_type": "bearer",
  "expires_in": 10800,
  "scope": "offline_access read write",
  "user_id":1234567,
  "refresh_token": "TG-5b9032b4e23464aed1f959f-1234567"
  }

Parametros da Credencial do conector no Omni

access_token usado na Credencial do conector no Omni no campo MERCADO_LIBRE_AUTH_TOKEN
refresh_token usado na Credencial do conector no Omni no campo MERCADO_LIBRE_REFRESH_TOKEN
APP_ID usado na Credencial do conector no Omni no campo MERCADO_LIBRE_CLIENTID
SECRET_KEY usado na Credencial do conector no Omni no campo MERCADO_LIBRE_CLIENTSECRET

O campo MERCADO_AUTH_URL da credential deve ser configurado com a seguinte URL:
https://chm-co.moddoplatform.com/chm/open/mercadoLibre/refreshToken/<SITEID_ML>

Onde SITEID_ML é o ID do site que representa o Mercado Livre na conta Omni do cliente.

O campo MERCADO_ACTIVAR_RETIRO de ser configurado com valor Si

O campo MERCADO_CURRENCY com o valor BRL

MERCADO_LISTING_TYPE indica o tipo de publicação do cliente. Configurar gold_special

E o código de país do Mercado Livre é configurado no campo MERCADO_MELI_COUNTRY_CODE. Para Brasil usar MLB

Estes dados serão utilizados em ambiente de Omni produção com a conta de produção do cliente.

Conta de Testes Mercado Livre

Para realizar os testes de publicação no Mercado Livre antes de configurar a conta de produção, 
devemos criar 2 usuários de testes no mercadolivre e designar um deles como comprador e outro como vendedor.

Siga o procedimento abaixo:

1) Criar usuários de testes para uso nos testes do conector fazendo a chamada abaixo 2 vezes para criar 2 usuários (um comprador e um vendedor):

curl -X POST -H "Content-Type: application/json" -d
'{"site_id":"MLB"}'
https://api.mercadolibre.com/users/test_user?access_token=ACCESS_TOKEN

Resposta exemplo:
{
"id":120506781,
"nickname":"TEST0548",
"password":"qatest328",
"site_status":"active"
}

2) Com um dos usuários gerados (o vendedor) logar em http://developers.mercadolivre.com.br,
Gerar um access token seguindo o mesmo procedimento descrito no passos 5 ao 9.

Com o código access_token e refresh_token deve-se configurar os parametros correspondentes da Credencial do conector no Omni.

Configurações Omni para Mercado Livre

1) Logado no Mercado Livre com a conta vendedora (conta vendedor de teste ou a conta do usuário) chamar a URL abaixo para obter o código do vendedor:

 https://api.mercadolibre.com/sites/MLB/search?nickname=TESTGZB7BZJ2

Exemplo Retorno:

{ "site_id": "MLB", "seller": { "id": 674940286, "nickname": null, "permalink": null, "registration_date": null, "real_estate_agency": false, ...}

Configurar o valor do seller > id no campo MERCADO_LIBRE_ORDERID da credencial do conector do mercado livre.

2) Acessar a interface web do TOTVS Omni com a conta do cliente > Gerenciador de canais > Categorias de links.

Selecionar no lado esquerdo as categoria do Omni que contenham produtos e associá-las às categorias do Canal.
NOTA: No caso de usar a conta de teste, pode associar categorias à categoria chamada pruebas.

3) Acessar a interface web do TOTVS Omni com a conta do cliente > Configurações > Sites 

Certifique-se que há uma loja associada ao Site principal e também ao site correspondente ao Mercado Livre.

Publicar Produtos no Mercado Livre

Criar uma publicação no TOTVS Omni e incluir pelo menos um produto da categoria mapeada.