Projeto: FS008696 - Integração VTEX - Orquestrador.
Nome do Cliente: Confederação Nacional da Indústria - SENAI
Objetivo
Este documento foi elaborado para orientar aos usuários chave do SENAI DN sobre os requisitos e funcionalidades do Orquestrador, customização aplicada ao TOTVS Educacional (SGE) que atua na integração entre a API do Protheus (que é de gestão do SENAI DN) e a Plataforma VTEX. A partir da leitura dos dados das vendas/pedidos realizados pela plataforma VTEX, o Orquestrador envia as informações para as API 's do PROTHEUS SENAI DN retornando o status da integração à plataforma VTEX.
Público Alvo
Este manual é destinado aos colaboradores selecionados como usuários chave para o Template Digital, SENAI DN.
Metodologia
Este material tem como base a visão prática e completa do Processo Customizado, da área Educacional através da Customização existente - FS008696 - Integração VTEX - Orquestrador.
A metodologia utilizada tem como ponto de partida o mapeamento completo do respectivo processo, relacionado com as interfaces no Sistema TOTVS Educacional (SGE). Sempre que houver alguma atividade a ser realizada no Sistema, as suas funcionalidades e rotinas serão explicadas com detalhe.
Esse projeto não trata exportações para o PROTHEUS (integração nativa), mas sim, para uma API do PROTHEUS que é exclusiva e de gestão do SENAI DN.
Premissas
Liberação dos anexos customizados na árvore de perfil:
Os anexos da customização - Integração VTEX devem ser liberados nas permissões de perfil dos usuários para aparecerem nos seus respectivos lugares. Para mais detalhes de como liberar no perfil dos usuários acesse o Manual de Instalação de Customizações na seção: Liberando Acesso aos Menus.
Parâmetros da Customização
A parametrização da customização da API do PROTHEUS deverá ser realizada de modo que sejam configurados as informações do endereço e dados de acesso para as API's do PROTHEUS (SENAI DN).
Essa parametrização está disponível em: TOTVS Educacional | Customização l Orquestrador VTEX l Parâmetros.
Na interface, os parâmetros processam a autenticação BASIC nas API's de exportação do PROTHEUS, para os quais o usuário deverá efetuar as seguintes parametrizações:
Consulta de Pedidos VTEX
O processo de consulta de pagamentos VTEX, identifica os dados associados aos pagamentos das vendas realizadas e/ou canceladas. Os dados de Pedidos VTEX, enviados para a API PROTHEUS DN, serão consultados por este processo (Maiores detalhes sobre o processo, cliquei aqui), mas será acrescentados a consulta dos campos abaixo:
Exportação de Clientes
Após consulta dos Pedidos (conforme citado no item anterior), é realizada a exportação para a API PROTHEUS DN. Esse processo exporta todos os dados consultados, realizando primeiramente uma identificação de cadastro de cliente pré-existente no PROTHEUS.
Esse processo pode ser agendado ou executado de forma manual através do Menu: TOTVS Educacional l Customização l Orquestrador VTEX l Exportação de Dados para o PROTHEUS.
As informações associadas ao cadastro de cliente enviadas ao PROTHEUS são:
Campo Protheus | Campo | Observações |
---|---|---|
Empresa | Empresa | Código da empresa PROTHEUS - Valor fixo 01 |
Filial | Filial | Código da filial - Valor fixo: 03DN0001 |
CPFCNPJ | CPF/CNPJ | CPF/CNPJ do cliente |
A1_PESSOA | Tipo Pessoa | F - Pessoa física / J: Pessoa jurídica |
A1_NOME | Nome Pessoa | Nome do responsável financeiro |
A1_INSCR | Inscrição Estadual | Pessoa física: Isento / Pessoa jurídica: Código de cadastro informado pelo cliente. Quando não preenchido: Isento |
A1_INSCRM | Inscrição Municipal | Pessoa física: Isento / Pessoa jurídica: Código de cadastro informado pelo cliente. Quando não preenchido: Isento; |
A1_END | Endereço | Logradouro do residência do cliente |
A1_COMPLEM | Complemento | Complemento do residência do cliente |
A1_CEP | CEP | CEP do cliente |
A1_BAIRRO | Bairro | Bairro do cliente |
A1_EST | Estado | Estado do cliente |
A1_COD_MUN | Código do Município | Código do Município do cliente |
A1_MUN | Município | Município do cliente |
A1_DDI | DDI | DDI do cliente |
A1_DDD | DDD | DDD do cliente |
A1_TEL | Telefone | Telefone do cliente |
A1_PAIS | Código do País | Código do país do cliente - Valor fixo 105 |
A1_EMAIL | E-mail do cliente | |
A1_SIMPNAC | Simples Nacional | Pessoa física: Valor fixo 2 / Pessoa jurídica: 1 para optante e 2 para não optante; |
A1_CONTRIB | Contribuinte ICMS | Pessoa física: Valor fixo 2 / Pessoa jurídica: Se possuir inscrição estadual - valor fixo 2, se não possuir inscrição estadual - envia vazio; |
A1_CNAE | Código CNAE | Quando informado pelo cliente, enviado conforme a máscara/formato: 9999-9/99. Quando não localizado no PROTHEUS, será apresentado erro, registrado no monitor de LOG da integração. |
A identificação de um cliente Seller (Pessoa jurídica) é realizada a partir da verificação do campo: Nome do Seller no cadastro do Item do pedido no Monitor de Vendas.
Para cliente do tipo: Seller cujo CNPJ já se encontra cadastrado no PROTHEUS, não será aplicada nenhuma atualização ao PROTHEUS. Já para um cliente do tipo: Seller que não tenha o CNPJ localizado/cadastrado no PROTHEUS, será apresentada uma mensagem de erro, gravado no monitor de LOG da integração.
Quando identificado mais de um cadastro de cliente associado a um mesmo CPF/CNPJ o processos executará as validações:
A customização verifica os itens do pedido, visto que, podem existir clientes diferentes para cada item de um mesmo pedido. O item do pedido não tem relação somente com o produto comprado, mas também com o cliente tipo: Seller.
Exportação de Contas a Receber
O processo de exportação de contas a receber envia os valores pagos no VTEX para API do PROTHEUS (SENAI DN). Enviando as informações financeiras associadas aos pedidos realizados na plataforma VTEX, que estejam com status: Pronto para manuseio.
O usuário deve utilizar o mesmo processo de exportação de cliente, uma vez que não será possível enviar clientes e contas a receber separadamente.
Neste processo serão enviados os dados da transação, valores e parcelas que compõem o pedido de acordo com a forma de pagamento:
Dados utilizados pela integração quando a forma de pagamento é por cartão de débito:
Campo Protheus | O que envia? | Observações |
---|---|---|
Empresa | Empresa | Código da empresa PROTHEUS - Valor fixo 01 |
Filial | Filial | Código da filial - Valor fixo: 03DN0001 |
Data_Venda | Data da Venda do Pedido | Data da Venda do Pedido |
E1_XFORMPG | Forma de Pagamento | CC - Cartão de Crédito / CD - Cartão de Débito / BOL - Boleto / PIX - Pagamento via PIX |
E1_XIDVTEX | OrderID VTEX | Código do pedido no VTEX |
E1_CLIENTE | Código do Cliente | Código do Cliente |
E1_LOJA | Loja do Cliente | Loja do Cliente |
E1_XCLIORI | Código do Seller no Protheus | Código cliente DR ou Parceiro - Para DN envia vazio |
E1_XLJORIG | Loja do Seller no Protheus | Loja DR ou Parceiro - Para DN envia vazio |
E1_XCOMIS | Valor da Comissão (repasse) | Valor da Comissão (repasse) - Para DN envia 0.00 |
E1_PEDIDO | Pedido de Venda | Pedido de Venda |
E1_CARTAO | Número do Cartão | Numero do cartão de crédito ou cartão de débito |
E1_CARTAUT | Código da Autorização | Código de autorização do cartão |
E1_NSUETF | NSU | NSU do cartão |
E1_XVLRDR | Valor total da Venda Seller | Valor total da Venda Seller - Caso seja DN envia 0.00 |
E1_XQPARDR | Quantidade de Parcelas Venda DR | Quantidade de Parcelas Venda DR - Caso seja DN envia 0 |
parcelas (E1_VALOR) | Parcelas | Valor de cada parcela do pedido |
Dados utilizados pela integração quando a forma de pagamento é por cartão de crédito:
Campo Protheus | O que envia? | Observações |
---|---|---|
Empresa | Empresa | Código da empresa PROTHEUS - Valor fixo 01 |
Filial | Filial | Código da filial - Valor fixo: 03DN0001 |
Data_Venda | Data da Venda do Pedido | Data da Venda do Pedido |
E1_XFORMPG | Forma de Pagamento | CC - Cartão de Crédito / CD - Cartão de Débito / BOL - Boleto / PIX - Pagamento via PIX |
E1_XIDVTEX | OrderID VTEX | Código do pedido no VTEX |
E1_CLIENTE | Código do Cliente | Código do Cliente |
E1_LOJA | Loja do Cliente | Loja do Cliente |
E1_XCLIORI | Código do Seller no Protheus | Código cliente DR ou Parceiro - Para DN envia vazio |
E1_XLJORIG | Loja do Seller no Protheus | Loja DR ou Parceiro - Para DN envia vazio |
E1_XCOMIS | Valor da Comissão (repasse) | Valor da Comissão (repasse) - Para DN envia 0.00 |
E1_PEDIDO | Pedido de Venda | Pedido de Venda |
E1_CARTAO | Número do Cartão | Numero do cartão de crédito ou cartão de débito |
E1_XVLRDR | Valor total da Venda Seller | Valor total da Venda Seller - Caso seja DN envia 0.00 |
E1_XQPARDR | Quantidade de Parcelas Venda DR | Quantidade de Parcelas Venda DR - Caso seja DN envia 0 |
parcelas (E1_VALOR) | Parcelas | Valor de cada parcela do pedido |
Dados utilizados pela integração quando a forma de pagamento é por boleto:
Campo Protheus | O que envia? | Observações |
---|---|---|
Empresa | Empresa | Código da empresa PROTHEUS - Valor fixo 01 |
Filial | Filial | Código da filial - Valor fixo: 03DN0001 |
Data_Venda | Data da Venda do Pedido | Data da Venda do Pedido |
E1_XFORMPG | Forma de Pagamento | CC - Cartão de Crédito / CD - Cartão de Débito / BOL - Boleto / PIX - Pagamento via PIX |
E1_XIDVTEX | OrderID VTEX | Código do pedido no VTEX |
E1_CLIENTE | Código do Cliente | Código do Cliente |
E1_LOJA | Loja do Cliente | Loja do Cliente |
E1_XCLIORI | Código do Seller no Protheus | Código cliente DR ou Parceiro - Para DN envia vazio |
E1_XLJORIG | Loja do Seller no Protheus | Loja DR ou Parceiro - Para DN envia vazio |
E1_XCOMIS | Valor da Comissão (repasse) | Valor da Comissão (repasse) - Para DN envia 0.00 |
E1_PEDIDO | Pedido de Venda | Pedido de Venda |
E1_XIDTRAN | Código da Transação | Código da Transação |
E1_NUMBCO | Nosso Número Boleto | Nosso Número Boleto |
E1_CODDIG | Código da Linha Digitável do Boleto Gerado | Código da Linha Digitável do Boleto Gerado |
E1_XVLRDR | Valor total da Venda Seller | Valor total da Venda Seller - Caso seja DN envia 0.00 |
E1_XQPARDR | Quantidade de Parcelas Venda DR | Quantidade de Parcelas Venda DR - Caso seja DN envia 0 |
parcelas (E1_VALOR) | Parcelas | Valor de cada parcela do pedido |
Dados utilizados pela integração quando a forma de pagamento é por PIX:
Campo Protheus | O que envia? | Observações |
---|---|---|
Empresa | Empresa | Código da empresa PROTHEUS - Valor fixo 01 |
Filial | Filial | Código da filial - Valor fixo: 03DN0001 |
Data_Venda | Data da Venda do Pedido | Data da Venda do Pedido |
E1_XFORMPG | Forma de Pagamento | CC - Cartão de Crédito / CD - Cartão de Débito / BOL - Boleto / PIX - Pagamento via PIX |
E1_XIDVTEX | OrderID VTEX | Código do pedido no VTEX |
E1_CLIENTE | Código do Cliente | Código do Cliente |
E1_LOJA | Loja do Cliente | Loja do Cliente |
E1_XCLIORI | Código do Seller no Protheus | Código cliente DR ou Parceiro - Para DN envia vazio |
E1_XLJORIG | Loja do Seller no Protheus | Loja DR ou Parceiro - Para DN envia vazio |
E1_XCOMIS | Valor da Comissão (repasse) | Valor da Comissão (repasse) - Para DN envia 0.00 |
E1_PEDIDO | Pedido de Venda | Pedido de Venda |
E1_XIDTRAN | Código da Transação | Código da Transação |
E1_XTXID | Código TXID Transação PIX | Código TXID Transação PIX |
E1_XDTHRPX | Data Venda | Data Hora do Pix |
E1_XVLRDR | Valor total da Venda Seller | Valor total da Venda Seller - Caso seja DN envia 0.00 |
E1_XQPARDR | Quantidade de Parcelas Venda DR | Quantidade de Parcelas Venda DR - Caso seja DN envia 0 |
parcelas (E1_VALOR) | Parcelas | Valor de cada parcela do pedido |
Exportação de Contas a Receber Seller
A identificação de um cliente Seller (Pessoa jurídica) é realizada a partir da verificação do campo: Nome do Seller no cadastro do Item do pedido no Monitor de Vendas, conforme citado anteriormente.
EXEMPLO
Pedido Id: 122550
Valor Total do Pedido: R$ 300,00
Itens do Pedido:
Verificados os itens do pedido, serão enviadas ao PROTHEUS duas contas a receber, conforme:
*COMISSÃO
O cálculo do valor correspondente a comissão a partir das vendas/pedidos de clientes do tipo Seller, é realizado considerando:
Valor do percentual da comissão x o Valor do Item .
Este será o valor enviado apenas para itens vendidos por Seller, dividido pelo número de parcelas. Caso o pagamento tenha sido parcelado, os valores serão enviados divididos pelo número de parcelas do pagamento do Pedido.
Pedido Id: 122552
Valor: R$ 100,00
Comissão: 10%
Itens do Pedido:
Total Comissão Seller SENAI Bahia: R$ 10,00
Pedido Id: 122552
Valor: R$ 300,00
Parcelamento: 02 Parcelas
Itens do Pedido:
Verificados os itens do pedido dividido em 2X, serão enviadas ao PROTHEUS duas contas a receber, conforme:
02 parcelas de R$10,00 (cada).
02 parcelas de R$50,00 (cada).
Pagamentos por PIX ou Boleto
Durante o processo de envio de Contas a receber, quando identificado que um pedido é da modalidade de pagamento pix ou boleto, a customização consultará o valor do repasse do Monitor de Vendas. Não será realizada a soma do repasse de cada item
Exportação de Contas a Pagar
O processo de consulta de pagamentos VTEX, identifica os dados associados aos pagamentos das vendas realizadas e/ou canceladas. Os dados de Pedidos VTEX, enviados para o PROTHEUS, serão consultados por este processo (Maiores detalhes sobre o processo, cliquei aqui).
Sempre que o processo de consulta de pagamentos VTEX, identificar vendas com status cancelado é gerado um 'contas a pagar', conforme detalhado abaixo:
Para pedidos Cancelados na VTEX:
PIX e Boleto
Para pedidos cancelados e que a forma de pagamento seja PIX ou Boleto, caso os dados bancários do Cliente não estejam preenchidos, não ocorrerá a exportação de contas a pagar.
Movimentação do Pedido VTEX
Sempre que a exportação de contas a receber é enviada com Sucesso para a API PROTHEUS; é enviado automaticamente para plataforma VTEX, uma atualização para que o Pedido passe do status: Pronto para manuseio para Faturado.
Essa atualização pode ser visualizada na tela do Monitor de Vendas, no campo Status Pedido:
O campo Status Protheus, também exibido na tela do Monitor de Vendas, a cada tentativa de Integração do Pedido com o PROTHEUS, terá seu valor atualizando, considerando:
Caso ocorra algum erro durante esse envio para plataforma VTEX, o usuário poderá consultar para que os ajustes necessários sejam providenciados.
Monitor de Log
O Monitor de Log, disponível em: TOTVS Educacional | Sistema Indústria | Orquestrador VTEX | Monitor de Log, armazena os dados exportados dos registros relacionados à Integração VTEX, possibilitando o acompanhamento e identificação dos registros exportados e importados com sucesso ou que necessitam ser reenviados.
A funcionalidade é baseada em duas visões, sendo a primeira o valor de registro principal e a segunda (Item Log) representando os detalhes de cada situação do registro principal.
Ao clicar sobre um registro de log, o usuário poderá consultar as demais informações complementares associadas ao registro, tais como:
No item de log terá disponível para consulta os seguintes campos:
Observação:
Os registros apresentados no monitor de log leitura não poderão ser manipulados, ou seja, não será permitido ao usuário realizar alterações como inclusão, edição e exclusão.
Para informações sobre Alteração Status Logs com Erro e o processo de Exclusão de Logs no monitor, acesse o Manual Operacional da Customização - LIB DN
Monitor de Log - Processo de Reenvio de Dados
Através do Monitor de Log, o usuário poderá processar o reenvio a API PROTHEUS dos registros que apresentam status de erro ou pendente, ou seja, que não foram exportados corretamente.
O processo de reenvio está disponível para execução em: TOTVS Educacional | Sistema Indústria | Orquestrador VTEX | Monitor de Log | Processos | Reenvio de Log.
O reenvio poderá ser executado de duas formas, a saber:
Ao processar o reenvio de log, a customização tentará realizar novamente o envio das informações ao PROTHEUS. Uma vez reenviado, o registro terá o seu status alterado para: Sucesso.
Observações: