Atenção!!!
Visite o link abaixo antes de escalonar chamados para o Desenvolvimento RZBusiness
Chamados escalonados fora do parão especificado serão cancelados
Manual de escalonamento de chamados de Integrações com ETL SysMiddle (wiki interna)
¶ Requisitos
- É obrigatório o preenchimento dos campos referência e marca para todos os produtos.
Cadastros\Estoque\Item
- É obrigatório, selecionar e integrar todas as marcas antes de iniciar o envio dos produtos.
Movimentações\Força de Vendas\Configuração de Registros para Integração
- É obrigatória, a criação da estrutura de árvore das categorias de produtos e-commerce e o vínculo de cada produto com a categoria e-commerce.
Cadastros\Estoque\Item
- É obrigatório que, todos os produtos tenham imagens vinculadas ao SKU na plataforma para poder ser ativado.
- Para que as imagens de produtos sejam enviadas automaticamente pela integração, é necessário disponibilizar um servidor WEB com FTP disponível e configurar uma conta que tenha permissão para realizar upload de arquivos e criação de pastas na pasta raiz do servidor WEB, e configurar os campos pertinentes na guia "configuração do serviço". O funcionamento do envio automático das imagens será discutido mais adiante neste documento. O envio das imagens também pode ser realizado manualmente através do painel de controle da plataforma.
- É obrigatório, o preenchimento das dimensões de todos os produtos (embalagem e dimensões reais).
Cadastros\Estoque\Item
- É recomendável o vínculo de uma categoria Google à categoria de produto e-commerce.
Cadastros\Estoque\Categoria E-Commerce
- Não é recomendável que nenhuma integração rode com bases de dados que estejam com o parâmetro 11 (Impedir duplicação de CPF/CNPJ no cadastro de parceiros) desabilitado. Além disso é altamente recomendável que casp haja parceiros duplicados, seja realizado um trabalho unificando os cadastros repetidos em um e que os demais sejam desabilitados (incluindo cliente/fornecedor).
- Para integrações que forem realizar vendas via Marketplace, é altamente recomendável habilitar no sistema a reserva de estoque e estar com o parâmetro 569 (Validar Estoque Deduzindo Estoque de Reserva) habilitado, pois a empresa pode ser penalizada pelo Marketplace caso o produto seja vendido e não haja estoque para entregar.
¶ Implantação
Os pré-requisitos de ajuste do cadastro devem ser realizados por um usuário que conheça bem o inventário da empresa. Este procedimento poderá ser demorado.
Somente prosseguir após ter certeza que os pré-requisitos obrigatórios tenham sido atendidos.
Antes de implantar, leia o manual da integração na íntegra, pois ele contém informações importantes sobre o funcionamento da integração.
¶ Configuração da integração
Aperte CTRL + M, e pesquise por "Configuração de integração força de vendas" e aperte Enter
Ou acesse o caminho:Arquivo\Configuração de integração força de vendas
Inclua uma integração de tipo V-Tex para a empresa que corresponda à empresa cadastrada no na API.
¶ Configurações
Arquivo\Configuração de integração força de vendas
Chave de acesso e token (AppKey e AppToken)
- Deverão ser geradas pelo usuário Owner da conta no painel da V-Tex.
Campos relacionados ao FTP e "Url raiz para a geração do link das imagens"
- Estes campos são necessários caso o cliente opte por enviar as imagens dos produtos automaticamente através da integração.
- Este serviço não é fornecido pela Razem, consulte o final deste documento para orientar o cliente sobre como contratar o serviço.
- O cliente também poderá optar por cadastrar as imagens manualmente para cada "SKU" dentro da plataforma, no entanto a plataforma não ativa o "SKU" enquanto não houver ao menos uma imagem pra ele.
ID de estoque
- Segundo a legisação vigente, um local de estoque precisa ser uma empresa devidamente constituída.
- Sendo assim, não é possível que uma loja fature um pedido que será entregue por outra empresa (no caso, um empresa que represente um estoque em outro local).
- Por este motivo, somente é suportado 1 estoque por loja na V-Tex.
- Complete o campo ID de estoque do cadastro de integração com o ID de estoque apresentado na plataforma em:
Pedidos > Estoque & Entrega > Estratégia de Envio > Estoques- A informação que precisa ser preenchida será semelhante a: "1_1".
¶ Recebimento
Arquivo\Configuração de integração força de vendas
- Cadastre o sacado (cadastro de parceiro) que representa o gateway de recebimentos contratado pela empresa (Ex: pague seguro, wirecard, etc.).
- Cadastre uma espécie de caixa "Cartão de Crédito" para utilizar com a integração:
- Vincule o sacado do passo anterior
- Inclua a bandeira "Diversos", e demais bandeiras que serão operadas, com vencimento 30 dias, e obtenha a taxa com o cliente.
- Na configuração da integração, na guia recebimentos, inclua uma configuração sem código, com a descrição "creditcard", selecione o tipo "Espécie de caixa" e em registro a gerar, selecione a espécie cadastrada no passo acima.
- Cadastre a condição de pagamento para ser utilizada nos cabeçalhos dos pedidos.
- Inclua uma condição de pagamento com tipo de cálculo "Automático calculado pelo Força de vendas".
- As demais configurações da condição de pagamento podem permanecer conforme o padrão do formulário.
- Na configuração da integração, na guia configurações, selecione a condição de pagamento e salve as alterações.
- Cadastre a condição de pagamento para recebimentos com boleto.
- Inclua uma condição de pagamento com tipo de cálculo "Automático", a prazo, e vincule o sacado do passo 1 acima.
- Fluxo: 100% do valor, carência: 0, referência: "Hoje", parcelas: 1, intevalo: 0.
- Na configuração da integração, na guia recebimentos, inclua uma configuração sem código, com a descrição "bankinvoice", selecione o tipo "Condição de pagamento" e em registro a gerar, selecione a condição cadastrada no passo acima.
¶ Entrega
Arquivo\Configuração de integração força de vendas
Acesse na plataforma:
Pedidos > Estoque & Entrega > Pontos de retirada
- Anote os IDs de cada ponto de retirada disponíveis, pois eles serão necessários para configurar os tipos de entrega "Retira".
Acesse na plataforma:
Pedidos > Estoque & Entrega > Estratégia de Envio > Políticas de envio
Acese a aba "Entrega" na configuração da integração e para cada registro contido nas políticas de envio da plataforma que represente o tipo "Entrega", inclua um registro com a descrição igual ao NOME da política de envio.
Para as políticas que representem o tipo "Retira", será necessário combinar o nome de cada política com os IDs dos pontos de retiradas anotados anteriormente. A descrição da configuração de entrega no Business deverá ser o "nome da política de envio", "espaço", "ID do ponto de retirada entre parênteses", conforme o exemplo: Retirada em Loja (Razem)
Utilize o help disponível no formulário para mais informações.
¶ Notificações
Arquivo\Configuração de integração força de vendas
Configure os alertas de usuário para a integração padrão, na guia "Notificações"
¶ Configurações dos almoxarifados
Aperte CTRL + M, e pesquise por "Configuração de registros para integração" e aperte Enter
Ou acesse o caminho:Movimentações\Força de Vendas\Configuração de Registros para Integração
Na aba "Saldo de estoque", configure para cada integração, quais almoxarifados e empresas devem ser considerados para enviar o saldo de estoque.
¶ Finalização das configurações
Na guia "Configurações" da integração, preencha os dados restantes.
¶ Instalação do serviço SysMiddle
Instale o serviço SysMiddle utilizando como nome do serviço o valor exibido no campo "Nome do Serviço" na configuração da integração no Business:
Arquivo\Configuração de integração força de vendas
Obtenha o valor da chave UrlVTex com o cliente.
Configure a chave PastaRaizVTex
Configure a string de conexão BDVTex
Caso a empresa não utilize reserva de estoque, o pacote "Get_Reserva_Estoque" poderá ser desabilitado.
¶ Instalação do Monitor do SysMiddle
Instale o monitor do SysMiddle, na mesma máquina onde o serviço SysMiddle foi instalado, com o nome "RAZEM - MONITOR - INTEGRACAO".
Marque a opção de atualização automática.
¶ Pré-carga de dados
- Acesse
Movimentações\Força de Vendas\Configuração de Registros para Integração, adicione todas as marcas.- Iniciar o servico SysMIddle e acompanhar a subida das marcas e das categorias de produtos e-commerce.
- Após concluir o envio dos passos 1 e 2, instrua o usuário a selecionar os produtos que serão enviados e acompanhe a carga de dados.
¶ Treinamento
Ministrar o treinamento conforme especificado no manual
¶ Informações importantes sobre o envio automático das imagens para a plataforma
As imagens de produtos no Business, são salvas na base de dados codificadas em Base64.
Algumas integrações recebem diretamente o texto em Base64 para montar a imagem. No entanto a V-Tex não funciona desta maneira. A V-Tex, recebe um LINK para o arquivo.
Sendo assim, é necessário hospedar a imagem em um servidor WEB público, para que a plataforma consiga "enxergar" a imagem e copiá-la para a sua estrutura dentro da plataforma.
Sendo assim, a integração das imagens funciona em etapas:
As imagens ainda não integradas são convertidas de volta em arquivo e enviadas para um servidor WEB público via FTP.
Após a confirmação que a imagem foi enviada com sucesso, a integração realiza uma requisição na API da V-Tex, passando o link no qual a imagem pode ser acessada.
Após a confirmação que o link foi recebido na plataforma, é incluído o registro na tabela intimagemproduto, bloqueando o envio desta imagem.
¶ Como configurar o envio de imagem FTP
Para funcionar corretamente o cliente deverá primeiramente contratar um servidor WEB e providenciar uma conta FTP, que tenha permissões para escrever arquivos e criar pastas no diretório público do servidor WEB.
A conta FTP deverá ficar configurada de modo que ao conectar-se no servidor, o diretório carregado seja algum diretório disponível dentro do diretório público do servidor WEB.
Além das credenciais da conta FTP, o cliente deverá fornecer a url do servidor web, que corresponda à pasta "home" da conta FTP.
Estes dados devem ser preenchidos nas configurações do serviço na configuração da integração.
Exemplo didático para testes:
Digamos que a url para as imagens seja a seguir:
URL: http://www.meudominio.com.br/ecommerce/imagens
A pasta "home" da conta FTP, deverá apontar para a pasta que corresponda a "PastaRaizDoServidorWeb/ecommerce/imagens".
Para testar se está funcionando corretamente siga os passos:
- Instale um cliente de FTP qualquer (filezilla por exemplo).
- Baixe um arquivo JPG qualquer da internet e nomeie-o como "teste.jpg".
- Conecte no FTP usando as credenciais fornecidas.
- Crie uma pasta com o nome "1", acesse esta pasta e copie o arquivo "teste.jpg" dentro dela.
- No seu browser, digite o seguinte endereço:
- http://www.meudominio.com.br/ecommerce/imagens/1/teste.jpg
- A imagem deverá aparecer carregada no browser.
- Após a conclusão dos testes, exclua todas as pastas criadas.
¶ Documentações técnicas
Documentação da API V-tex.
NUNCA exclua registros diretamente na plataforma, pois resultará em falhas de sincronia na integração.
¶ Recursos disponíveis:
¶ 1. Marcas
- Envia cadastros de marcas para a API. (Inclusão e alteração).
- Serão enviados os cadastros das marcas selecionadas no formulário de seleção de registros a integrar.
- Definição dos campos enviados:
Nome da entidade: "Brand".
O campo "Descrição" do cadastro de marcas do sistema é enviado "capitalizado" nos elementos "Name", "Text" e "SiteTitle".
Esta entidade é obrigatória visto que o cadastro de um produto é rejeitado quando enviado sem o devido relacionamento com ela.
¶ 2. Categorias de produtos e-commerce
- Envia a hierarquia de categorias de produtos e-commerce (Inclusão e alteração).
- Cadastro de categorias:
Cadastros\Estoque\Categoria E-Commerceou diretamente no cadastro do item, na guia "e-commerce".- Toda a hierarquia cadastrada é enviada sem a necessidade de se selecionar no formulário de seleção de registros a integrar, devido a necessidade de enviar toda a estrutura hierárquica e de se tratar de um cadastro exclusivo para o e-commerce.
- Definição dos campos enviados:
- Nome da entidade: "Category"
- O campo "Nome" é enviado "capitalizado" nos elementos "Name" e "Title".
- O campo "Descrição" é enviado no elemento "Description".
- O campo "Categoria pai" é enviado no elemento "FatherCategoryId".
- O campo "Categ. Google Merchant" é enviado no elemento "globalcategoryid".
- O campo "Tags/ Meta Keywords" é enviado no elemento "Keywords".
Esta entidade é obrigatória visto que o cadastro de um produto é rejeitado quando enviado sem o devido relacionamento com ela.
¶ 3. Produtos
- Envia cadastros de produtos (Inclusão e alteração).
- A plataforma separa o cadastro de produtos utilizando um conceito no qual existe a definição do produto, que seria um conceito abstrato e os SKU para o produto que seriam as representações concretas das diferentes apresentações de determinado produto.
- Quando o tipo de controle do produto no Business for Unitário, cada produto terá um SKU correspondente.
- Quando o tipo de controle do produto no Business for Grade, cada produto terá um SKU para cada configuração de grade do produto.
- Serão enviados os cadastros dos produtos selecionadas no formulário de seleção de registros a integrar.
¶ Inclusão
Inclusão de novo cadastro de produtos na API é realizado em fases:
- Envio do cadastro do produto.
- Envio do(s) SKU(s) do produto. (Registro auxiliar de produtos)
- Envio do preço do produto.
- Envio do estoque do produto.
- Envio da(s) Imagem(ns) do produto.
- Ativação do(s) SKU(s) do produto.
- Cada fase realiza um conjunto separado de envio e recebimento de informações com a API.
- Sendo assim, pode ocorrer que determinado produto não esteja ativo na API devido a falha em alguma das fases.
- Para determinar o motivo, se faz necessário o acompanhamento de cada fase separadamente no formulário "Acompanhamento fila de registros integração".
- A fase 5, pode ser realizada automaticamente através da integração (necessário contratar e implantar o serviço FTP descrito nos requisitos) ou manualmente, com o usuário definindo as imagens para os SKU diretamente na plataforma.
- No entanto, a VTex não ativa o SKU enquanto não houver ao menos uma imagem definida para ele.
¶ Atualização:
A atualização de cadastros já enviados ocorre de maneira unitária de acordo com qual fase precisa ser atualizada.
A - Atualização do cadastro do produto
B - Atualização dos dados físicos do produto ex: Medidas
C - Atualização de preço
D - Atualização de estoque
E - Envio de novas imagens
¶ Nome da entidade: "Product"
- O campo "Descrição curta" da guia "E-Commerce" quando preenchido, é enviado "capitalizado" no elemento "Name". Quando não preenchido é enviado o campo "Descrição" da guia principal, "capitalizado". A mesma regra é utilizada no preenchimento do elemento "title".
- O campo "Referência" da guia "principal" é enviado no elemento "RefId".
- O campo "Código NCM" da guia "Fiscal" é enviado no elemento "TaxCode".
- O campo "Descrição SEO / Slug" da guia "E-Commerce" é enviado no elemento "MetaTagDescription"
- O campo "Descrição longa" da guia "E-Commerce" é enviado no elemento "Description".
- O campo "Descrição curta" da guia "E-Commerce" é enviado no elemento "DescriptionShort".
- O campo "Tags / Meta Keywords" da guia "E-Commerce" é enviado no elemento "KeyWords"
- A categoria e-commerce é enviada no elemento "CategoryId" com o código recebido da API após o envio da categoria vinculada.
- A marca do produto é enviada no elemento "BrandId" com o código recebido da API após o envio da marca vinculada.
- Para inativar um produto e todos os seus SKU na plataforma, no formulário de registros a integrar, altere o seu percentual de estoque para ZERO.
¶ Nome da entidade: "SKU"
- Para produtos de tipo de controle "unitário", o campo "Descrição curta" da guia "E-Commerce" quando preenchido, é enviado "capitalizado" no elemento "Name". Quando não preenchido é enviado o campo "Descrição" da guia principal, "capitalizado".
- Para produtos de tipo de controle "grade", o campo "Descrição grade" é enviado "capitalizado" no elemento "Name".
- Para produtos de tipo de controle "unitário", o campo "Referência" da guia "principal" é enviado no elemento "RefId".
- Para produtos de tipo de controle "grade", o campo "Referência da grade" é enviado no elemento "RefId".
- O grupo de confgurações "Dimensões do produto em metros" da guia "Complemento" é enviado nos elementos "Height", "Width", "Length" respectivamente, representando as dimensões reais do produto.
- O grupo de confgurações "Dimensões da embalagem do produto em metros" da guia "Complemento" é enviado nos elementos "PackageHeight", "PackageWidth", "PackageLength" respectivamente, representando as dimensões do produto com a embalagem.
- O campo "Peso Líquido KG" da guia "Fiscal" é enviado no elemento "WeightKG".
- O campo "Peso Bruto KG" da guia "Fiscal" é enviado no elemento "PackageWeightKG" representando o peso do produto com a embalagem.
- O campo "Código/Referência (fabricante)" da guia "Dados Complementares" é enviado no elemento "ManufacturerCode".
¶ 4. Estoque e preço
- Envia atualização de estoque e preço, conforme descrito nas fases do item 1.2.
- O preço considerado será o preço válido na data corrente na tabela vinculada ao produto no formulário de seleção de registros integração.
- O saldo de estoque enviado será calculado com base no percentual vinculado ao produto no formulário de seleção de registros integração, considerando-se:
- Os almoxarifados e empresas configurados para a integração.
- A reserva de estoque, onde configurado.
¶ 5. Imagens de produtos
- Envia todas as imagens do produto, configuradas como "Enviar para força de vendas".
- A imagem principal de cada produto, é enviada independentemente de estar configurada como "Enviar para força de vendas".
- A API não ativa o SKU caso não exista nenhuma imagem disponível pra ele na plataforma.
- A API rejeita imagens cuja resolução seja inferior a 1000x1000 pixels.
- Formatos testados: jpg, png.
¶ 6. Clientes e endereços
- Novos clientes, novos endereços de entrega. A internalização dos dados de novos clientes e endereços de entrega é realizada juntamente com a internalização do pedido força de vendas.
¶ Endereço:
- A API não fornece o endereço do cliente quando o tipo de entrega selecionado é "Retirar na Loja".
- Como os dados do endereço no Business são mandatórios para o cadastro do parceiro, nese caso o cliente será cadastrado com o endereço do ponto de retirada que ele selecionou no pedido.
- Em outro momento, caso o mesmo cliente realize um pedido de tipo de etrega "Entrega", um novo endereço de entrega será cadastrado pra ele e o pedido assumirá este endereço, no entanto o endereço da capa do cadastro do parceiro não será alterado.
¶ E-mail:
- Quando o cliente fecha um pedido sem estar logado na plataforma, o endereço de e-mail que vem disponível no cadastro, é um e-mail interno da plataforma.
¶ 7. Pedidos força de vendas
¶ Recebe:
- Pedidos com pagamento aprovado e status "Pronto para manuseio", são internalizados na base de dados e disponibilizados no formulário de importação de dados força de vendas, onde permanecerão até que algum usuário os selecione para geração de pedido de venda.
- Após a internalização do pedido, a integração atualiza o status do pedido na plataforma para "Preparando entrega" de modo que uma vez internalizado, um pedido não aparecerá novamente na lista de pedidos disponíveis para integrar, visto que o status do pedido estará diferente de "Pronto para manuseio".
- Pedidos aguardando aprovação de pagamento, são internalizados como reserva de estoque, se a integração estiver configurada para tal.
- Ao gerar com sucesso um pedido de venda a partir de um pedido força de vendas internalizado, a reserva de estoque da força de vendas é automaticamente excluída.
- Pedidos cancelados, são cancelados automaticamente na internalização quando não houver atendimento prévio do pedido.
- Caso já exista atendimento para o pedido força de vendas, o cancelamento do pedido é importado como "Pendente" e fica disponível no formulário de importação de dados força de vendas, na guia cancelamentos, para que o usuário realize o estorno do fluxo conforme necessário (separação de mercadorias, cancelamento de NF, etc.).
¶ Atualiza os status do pedido (Followup):
- A - Após faturar totalmente o pedido, envia os dados da(s) nota(s).
- B - Ao informar a saída para a entrega (Atendimento pedido de venda), envia os códigos de rastreio se informados e comanda a atualização do status.
- C - Ao confirmar a entrega (Atendimento pedido de venda), comanda a atualização do status.
- D - Ao cancelar o pedido no Business, envia o cancelamento.
¶ 2. Treinamento necessário
- Formulário de seleção de registros a integrar.
- Formulário de importação de dados força de vendas.
- Formulário de consulta de logs de importação (Pedido, cliente, endereço).
- Formulário de acompanhamento de registros integração.
- Esclarecimento referente aos itens pertinentes nos requisitos.
¶ Solução de problemas
Esta seção está constantemente em construção.
Contribua com a sua melhoria contínua.
- Para problemas referente ao funcionamento do serviço, clicar no link abaixo:
Wiki de solução de problemas referente ao serviço