CONTEÚDO
- Visão Geral
- Regras de utilização no Totvs Ipass
- Regras de utilização do ERP
- Dicionário de Campos
- Acompanhamento das cargas no Hubecommerce
- Links úteis
01. VISÃO GERAL
Esta documentação tem como objetivo descrever como funciona a integração de envio de Pedidos de Venda da plataforma de E-commerce Shopify para o ERP TOTVS Varejo Supermercados, utilizando a plataforma TOTVS iPaaS como middleware de comunicação.
02. REGRAS DE UTILIZAÇÃO NO TOTVS IPASS
O fluxo de integração via Ipass, contempla a seguinte estrutura, o Pedido de Venda vindo do Shopify é recepcionado no Ipass via webhook, para envio dos dados do pedido do ERP para o Hub, após inserção no mesmo, o Ipass seguirá no fluxo de montagem e validação do pedido, onde atenderá premissas como confirmação de pagamento, para que este siga o processo de integração, após este este passo, o Ipass seguirá para o recepcionamento do pedido no ERP onde este será feito via API SmPedidoVenda/api/v1/PedidoVenda, onde ao atender as regras de negócio do ERP, o pedido terá sua integração concluída.
Especificações e configurações para envio da carga de Pedido de Venda do Shopify para o ERP:
- Nrosegmento - Utilizada para obtenção do segmento padrão, em que será utilizado para busca do SKU no ERP, ao qual será enviado ao Shopify (variável no Ipass: nrosegmento)
- Seqcanalvenda - Utilizada para obter o canal de venda que está sendo utilizado pelo ERP, para integração de pedidos de e-commerce, neste caso, deverá ser criado um Canal de Venda específico para o Shopify. O código deste canal de venda será encontrado no ERP no Módulo Vendas > Pedido de Venda/Transferência > Integração Api > Cadastro Canal de Venda > Campo: Sequência (variável no Ipass: seqcanalvenda)
- Codgeraloper - Utilizada para definir o CGO padrão, no qual será realizada a integração do pedido no ERP. (variável no Ipass: codgeraloper)
- Nrorepresentante - Utilizada para obter qual o representante padrão para a integração de pedidos de venda, vindos do Shopify. (variável no Ipass: nrorepresentante)
- Nrotabvenda - Utilizada para obtenção da tabela de venda padrão, para a integração de pedidos de venda, vindos do Shopify. (variável no Ipass: nrotabvenda)
- Tiporateiofretepedido - Utilizada para definição do tipo e forma de rateio de frete padrão no pedido, ao qual será empregado na integração, caso haja frete. (variável no Ipass: tiporateiofretepedido)
- Versão da API do Shopify - A configuração de qual versão da Api de integração do Shopify está sendo utilizada, é definido através das variáveis de projeto no Ipass, representada pela variável api_version. Importante ressaltar que a variável deve ser alterada apenas pela Totvs, pois, uma alteração sem aviso prévio poderá ocasionar problemas na integração com a plataforma Shopify
Para alterar variáveis de projeto no Ipass, basta, no aplicativo Totvs Ipass, ir à barra de navegação na lateral esquerda e selecionar a opção Integrações. Após esse passo, selecione o projeto no qual está localizada a integração com o Shopify e clique na opção Configurar Projeto, localizada na parte superior da tela. Feito isso, aparecerá a seção de Variáveis, na qual será possível alterar cada variável conforme a necessidade de configuração da integração.
Detalhamento do fluxo de configuração de variáveis
Menu Integrações
Configurações do Projeto
Variáveis do Projeto
03. REGRAS DE UTILIZAÇÃO DO ERP
- O canal de venda no qual, será utilizado para a integração com o Shopify, deverá estar cadastrado em Vendas > Pedido de Venda/Transferência > Integração Api > Cadastro Canal de Venda. (mad_canalvenda.seqcanalvenda)
Exemplo:
04. DICIONÁRIO DE CAMPOS
Campos utilizados no fluxo de integração de pedidos do Shopify para o Hub.
Campo no Hub | Campo no Shopify |
| eCommerceReferenceKey | order.id |
| orderId | order.id |
| sequenceId | order.id |
| orderStatusECommerceReferenceKey | order.financial_status |
| eCommerceCreateDate | order.created_at |
| eCommerceLastChange | order.updated_at |
| totalValue | order.total_price |
| listOfTotal.Items.value | order.total_line_items_price |
| listOfTotal.Discounts.value | order.current_total_discounts |
| listOfTotal.Shipping.value | order.shipping_lines.price |
| listOfTotal.Tax.value | order.current_total_tax |
| totalValue | order.total_price |
| listOfOrderPayment.paymentMethodECommerceReferenceKey | order.payment_gateway_names |
| customer.eCommerceReferenceKey | order.customer.id |
| customer.firstName | order.customer.first_name |
| customer.lastName | order.customer.last_name |
| customer.email | order.customer.email |
| customer.phone | order.customer.phone |
| customer.addressInfo.street | order.shipping_address.address1 |
| customer.addressInfo.receiverName | order.shipping_address.name |
| customer.addressInfo.postalCode | order.shipping_address.zip |
| customer.addressInfo.city | order.shipping_address.city |
| customer.addressInfo.state | order.shipping_address.province_code |
| customer.addressInfo.country | order.shipping_address.country_code |
| customer.addressInfo.complement | order.shipping_address.address2 |
| listOfOrderItem.eCommerceReferenceKey | order.line_items.id |
| listOfOrderItem.productSKUECommerceReferenceKey | order.line_items.variant_id |
| listOfOrderItem.quantity | order.line_items.quantity |
| listOfOrderItem.price | order.line_items.price |
| listOfOrderItem.listPrice | order.line_items.listPrice |
| listOfOrderItem.sellingPrice | order.line_items.sellingPrice |
| listOfOrderItem.isGift | order.line_items.gift_card |
| listOfOrderItem.discontValue | order.line_items.discount_allocations.amount |
| salesChannel | order.order_status_url |
| extraText1 | fulfillment.fulfillment_orders.delivery_method.min_delivery_date_time |
| extraText2 | fulfillment.fulfillment_orders.delivery_method.max_delivery_date_time |
Campos utilizados no fluxo de integração de pedidos do Hub para o ERP, através do endpoint GET SmPedidoVenda/api/v1/Cadastros/ProdutoSku, e suas respectivas referências no Hub e no ERP.
Campo | ERP (Linha Consinco) | Hub |
seqCanalVenda | Vendas > Pedido de Venda/Transferência > Integração Api > Cadastro Canal de Venda > Campo: Sequência. | variável seqcanalvenda |
| idPedidoCanalVenda | Será o Id do pedido de Venda vindo da plataforma Shopify. | orderId |
| dtaHorPedidoCanalVenda | Será populado com a data de criação do pedido na plataforma Shopify. | eCommerceCreateDate |
| nroEmpresa | Parâmetros > Parâmetros > Empresa> Aba Geral > Empresa (max_empresa.nroempresa) | erpCompanyId |
| nroSegmento | Utilizada para obtenção do segmento em que será utilizado para a inserção do Pedido no ERP. | variável nrosegmento Observação: Informação sobre configuração da variável nrosegmento no Ipass está presente no item 2 - Regras de Utilização no Totvs Ipass. |
| codGeralOper | Parâmetros > Aba Parâmetros > Código Geral de Operação > Campo: C.G.O | variável codGeralOper |
| nroTabVenda | Parâmetros > Aba Dealer > Tabela de Venda > Campo: Código | variável nroTabVenda Observação: Informação sobre configuração da variável codGeralOper no Ipass está presente no item 2 - Regras de Utilização no Totvs Ipass. |
| seqTransportador | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| tipoEntrega | Representa o tipo de expedição, é informado em Pedido de Venda > Campo: Exped. E - Entrega, R - Retira. | orderCarrierERPReferenceKey |
| obsPedido | Observações acerca do pedido, enviado da shopify para o ERP. Visualização disponível em Pedido de Venda > Campo: F11 Obs. | observation |
| obsNotaFiscal | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| vlrTotFrete | Valor total do Frete, enviado ao cabeçalho do pedido do Shopify para o ERP. Visualizado em Pedido de Venda > Campo: Vlr. Frete. | freightValue |
| tipoRateioFretePedido | Informação pertinente ao modo de rateio de frete no pedido de Venda, ao integrar no ERP. | variável tipoRateioFretePedido Observação: Informação sobre configuração da variável tipoRateioFretePedido no Ipass está presente no item 2 - Regras de Utilização no Totvs Ipass. |
| tipoFreteDocAuxiliar | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| indIntermediador | É enviado ao ERP como Default N, pois o Shopify não trata operação de intermediador de negociação. | Não Existe |
| dtaHorIniPrevEntrega | Data e Hora de início de janela de previsão de entrega. | extraText1 |
| dtaHorFimPrevEntrega | Data e Hora fim de janela de previsão de entrega. | extraText2 |
| clienteDto.cpfCnpj | CPF ou CNPJ do Cliente no Shopify. Cliente > Cliente > Pessoa > Aba Geral > Caso seja Pessoa Física o Campo é: CFP, caso seja Pessoa Jurídica, o Campo é: CNPJ. | customerDocument |
| clienteDto.inscEstadualRg | Não é enviado ao ERP, pois não existe esta informação no Shopify. Cliente > Cliente > Pessoa > Aba Geral > Caso seja Pessoa Física o Campo é: RG, caso seja Pessoa Jurídica, o Campo será: IE. | Não Existe |
| clienteDto.nomeRazaoSocial | Nome ou Razão Social do cliente no Shopify, ao qual é enviado ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Nome/Razão. | customerFullName |
| clienteDto.nomeFantasia | Nome Fantasia do cliente no Shopify, ao qual é enviado ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Fantasia. | customerFullName |
| clienteDto.sexo | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| clienteDto.cidade | Cidade do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Cidade. | customerAddressCity |
| clienteDto.uf | UF do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: UF. | customerAddressState |
| clienteDto.pais | País do cliente no Shopify, no qual é enviado ao ERP. | customerAddressCountry |
| clienteDto.bairro | Bairro do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Bairro. | customerAddressNeighborhood |
| clienteDto.logradouro | Logradouro do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Logradouro. | customerAddressStreet |
| clienteDto.nroLogradouro | Número do Logradouro do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Nº. | customerAddressNumber |
| clienteDto.complementoLogradouro | Complemento do endereço do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Complemento . | customerAddressComplement |
| clienteDto.cep | CEP do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: CEP. | customerAddressCep |
| clienteDto.foneDdd1 | DDD do telefone do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Contatos > Campo: DDD. | customerPhoneNumberDDD |
| clienteDto.foneNro1 | Número do telefone do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Contatos > Campo: Nro. | customerPhoneNumber |
| clienteDto.dtaNascFund | Data de nascimento do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Geral > Campo: Data Nascimento. | customerBirthDate |
| clienteDto.email | Email do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Contatos > Campo: Email | customerEmail |
| clienteDto.emailNfe | Email NFE do cliente no Shopify, ao qual será enviada ao ERP. Cliente > Cliente > Pessoa > Aba Contatos > Campo: Email. | customerEmail |
| clienteDto.estadoCivil | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| clienteDto.inscMunicipal | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| clienteDto.inscProdutor | É enviado ao ERP como nulo, pois não há informações acerca deste campo no Shopify. | Não Existe |
| clienteDto.indContribIcms | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| clienteDto.fisicaJuridica | Tipo de Pessoa, relacionado ao cliente no Shopify, ao qual será enviada ao ERP, será Física(F) ou Jurídica(J). Cliente > Cliente > Pessoa > Aba Geral > Campo: Tipo. | customerDocumentType |
| itemDto.codAcesso | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| itemDto.seqProduto | Refere-se ao Código do Produto no ERP, localizado em Cadastros > Aba Produto > Produto > Aba Geral > Campo: Código (Código do Produto). | listOfOrderItem.productSKUERPReferenceKey |
| itemDto.qtdPedida | Pedido de Venda > Grid de itens do Pedido > Campo: Quant Solicit. | listOfOrderItem.quantity |
| itemDto.qtdEmbalagem | Quantidade da embalagem do produto no Cadastro de família, em Cadastros > Aba Família > Família> Aba Embalagens > Campo: *Quantidade. | listOfOrderItem.productSKUERPReferenceKey |
| itemDto.vlrEmbTabPreco | Pedido de Venda > Grid de itens do Pedido > Campo: Preço Tabela. | listOfOrderItem.sellingPrice |
| itemDto.vlrEmbInformado | Pedido de Venda > Grid de itens do Pedido > Campo: Preço Pedido. | listOfOrderItem.listPrice |
| itemDto.vlrEmbDesconto | Valor de desconto por embalagem. | listOfOrderItem.discontValue |
| itemDto.observacaoItem | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| itemDto.qtdVolume | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| itemDto.indSimilarEcommerce | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| itemDto.indKit | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| itemDto.vlrTotComissao | Valor de comissão sobre a venda do produto. | listOfOrderItem.commission |
| itemDto.fatorMultiplicador | Não é enviado ao ERP, pois não há informações acerca deste campo no Shopify. | Não Existe |
| itemDto.seqItemCanalVenda | Sequencial de cada produto do Pedido de Venda. Pedido de Venda > Grid de itens do Pedido > Campo: Nro Item. | listOfOrderItem.position |
| itemDto.indBonificado | Indicador de bonificação em produtos, caso o mesmo seja no pedido um item bonificado. Default será N, caso não seja enviado nenhum valor ao ERP. | Observações: O retorno deste campo para o ERP é definido através da seguinte regra: Caso a subtração dos campos listOfOrderItem.sellingPrice, com o campo listOfOrderItem.discontValue seja 0, a integração retornará indBonificado = "S", caso seja maior que zero, é retornado como Default "N", ou seja, a integração sempre irá considerar a subtração entre os campos listOfOrderItem.sellingPrice - listOfOrderItem.discontValue, para a tomada de decisão. Lembrando que estes campos são pertencentes ao HUB. |
| pagamentoDto.cpfCnpjCartao | CPF ou CNPJ do Cliente no Shopify. Cliente > Cliente > Pessoa > Aba Geral > Caso seja Pessoa Física o Campo é: CFP, caso seja Pessoa Jurídica, o Campo é: CNPJ. | Caso no Hub, o campo customerDocumentType = CPF então, o campo retornado será customerDocument, agora, caso o campo customerDocumentType = CNPJ, o campo retornado será customerCorporateDocument. |
| pagamentoDto.nroFormaPagto | Código da Forma de Pagamento no ERP. Parâmetros > Aba Dealer > Forma de Pagamento > Campo: Código. | listOfOrderPayment.erpReferenceKey Observações: Esta informação é cadastrada no HubEcommerce em https://hubecommerce.totvs.app/payment-method > Cadastrar > Campo: Código do ERP. Será preenchido com o código da Forma de pagamento do ERP. |
| pagamentoDto.nroCondPagto | Código da Condição de Pagamento no ERP. Parâmetros > Aba Dealer > Condição de Pagamento > Campo: Código. | listOfOrderPayment.cdCondpgto Observações: Esta informação é cadastrada no HubEcommerce em https://hubecommerce.totvs.app/payment-method > Cadastrar > Campo: Código da condição de pagamento (cdCondpgto). Será preenchido com o código da condição de pagamento do ERP. |
| pagamentoDto.valorPagto | Representa o valor ao qual foi realizado o pagamento do pedido no Shopify. | listOfOrderPayment.value |
| pagamentoDto.nroParcela | Refere-se ao número de parcelas pertinentes ao pagamento do pedido no Shopify. | listOfOrderPayment.installments |
05. ACOMPANHAMENTO DAS CARGAS NO HUBECOMMERCE
Painel de monitoramento: https://hubecommerce.totvs.app/orders
06. LINKS ÚTEIS
Link: Detalhamento do fluxo
Visão Geral
Import HTML Content
Conteúdo das Ferramentas