Histórico da Página

1. VISÃO GERAL

Implementada a funcionalidade de Integração BackOffice do sistema Microsiga Protheus® (Importante: para release 12.1.25 ou superior) com o sistema E-Commerce da VTEX®, possibilitando a troca de informações e processos detalhados abaixo.

Os dados são enviados/recebidos por meio da mensagem padronizada TOTVS com a funcionalidade EAI (Enterprise Application Integration), disponível no módulo Configurador.

Nesse modelo as integrações serão direcionandas diretamente a rotina MATA410 (Pedido de Vendas).

2. DETALHAMENTO

Deck of Cards

id	Cenario
effectType	fade

Card

id	1
label	Preparação Integração EAI
effectType	fade

Expandir

title	Configuração EAI

Expandir

title	Configurações Iniciais

Nota

title	Importante!

Funcionalidade disponível somente na release 12.1.25 ou superior.
Verifique se existem campos com obrigatoriedade diferente do padrão Protheus, pois esse tipo de validação pode impactar no recebimento das Mensagens.
A integração de Produto não ocorrerá caso seja utilizada a rotina Cadastro de Produto (LOJA110) presente no módulo Controle de Lojas (SIGALOJA).
É imprescindível que o endereço de comunicação/Porta informado pela VTEX e endereço de Comunicação/Porta do serviço REST e Schedule estejam liberados no servidor da aplicação Cloud TOTVS ou Outros para receber e enviar informações.

RPO atualizado
É imprescindível estar com a Lib atualizada:
Versão mínima da Lib:20190131
Data da Lib: 20190215_9053
É imprecindível estar com o Binário atualizado.
Versão mínima da Build AppServer: 7.00.131227A-20190114 NG
É imprescindível efetuar a configuração do Appserver e DBAccess, para suportar mensagens com até 30MB.

A ausência dessa configuração pode gerar o erro de "String size overflow" para mensagens com muitos itens.

Arquivo Appserver.ini:

Efetue a inclusão das chaves abaixo:

[Environment]

TopMemoMega =30

[General]

MaxStringSize=30

Exemplo:

No DBAccess altere o arquivo DBAccess.ini:

Efetue a inclusão da chave abaixo:

[General]

MaxStringSize=30

Exemplo:

Para mais detalhes, acesse o link : Melhoria - Suporte a campo MEMO com mais de 1 MB

Expandir

title	Cadastro de Rotas EAI

Para que o Protheus seja capaz de enviar ou receber mensagens para VTEX é necessário que seja configurado as Rotas, informando o endereço HTTP do servidor VTEX.

1. Para isso utilize a rotina Cadastro de Rotas EAI no Módulo Configurador(SIGACFG) na opção Ambiente\Schedule\Cadastro de Rotas EAI.

2. Pressione o botão Incluir para cadastrar a rota do sistema VTEX

3. Preencha os campos da tela abaixo:

Onde:

Produto : Deve conter o nome do Produto com o qual o PROTHEUS irá ser integrado. Deve-se obrigatoriamente usar a palavra: VTEX

Aplicação : Deve ser o nome do Produto utilizado na integração (obs.: Quando recepcionamos uma mensagem da VTEX, o sistema verifica este campo que deve estar de acordo com a TAG <SourceApplication> ) Deve-se obrigatoriamente usar a palavra: VTEX

Url : É o caminho ou endereço do servidor de destino. A URL deve ser solicitada para VTEX

Client WS : É o tipo do cliente utilizado. Padrão: WSEAISERVICE

Metodo : É o método do utilizado para a integração. Padrão: receiveMessage

Usuário : Usuário utilizado caso o destino obrigue a ter um usuário padrão

Canal Env : Especificamos o tipo da integração que para VTEX deve ser 2-REST

Senha : Palavra chave para a validação e liberação dos acesso no destino , caso este precise de validação

Expandir

title	REST EAI

Para que o EAI Protheus seja capaz de receber mensagens da VTEX (para o envio o Protheus não faz o consumo do seu serviço Web, e sim do serviço do outro sistema) é necessário que seja habilitado o protocolo HTTP/REST no servidor e que as configurações de WebServices estejam ativas.

Para isto é necessário configurar o arquivo appserver.ini do servidor Protheus.

Para isso é necessário configurar o REST Padrão do Protheus. Veja mais detalhes nos links abaixo:

Configuração do serviço REST Configuração REST SERVER - Protheus.
Mais detalhes sobre o conceito de um serviço REST clique aqui.
Para mais detalhes sobre serviços REST na arquitetura Protheus clique aqui.

Exemplo de configuração Protheus REST:

Analisando um exemplo de REST no Appserver.ini:
Inicie o navegador de Internet e informe o endereço do servidor e da porta do serviço REST ex: http://127.0.0.1:8070
Observe a apresentação da Lista serviços REST disponíveis:
Realize o teste de uma rede externa(3G/Outra Rede fora da empresa) para saber se o acesso externo está liberado.

Deve aparecer a lista de serviços como no exemplo abaixo:

3 - Na lista de Serviço localize o serviço EAISERVICE:

Clique em "For more details" para exibir os detalhes do serviço:

4 - Nos Detalhes do serviço localize o serviço do tipo POST de nome: "standardmessage/v1/transactions"

Esse é o serviço responsável por receber as mensagens da VTEX

5 - Será necessário enviar o Endereço do Serviço Protheus para VTEX.

O endereço é formado pelo IP do servidor(IP Externo) e porta definido no serviço REST + totvseai/standardmessage/v1/transactions/

O caminho do serviço completo ficaria assim: http://127.0.0.1:8070/totvseai/standardmessage/v1/transactions/

Dica

title	Dica

Caso tenha definido um caminho para o serviço REST em URL o mesmo deve ser considerado no caminho do serviço.

Isso evita erros como: {"code":404,"detailedmessage":"","message":"The server can't find the requested resource."}

Ex :

[HTTPURI]
URL=/REST

então o caminho ficaria: http://127.0.0.1:8070/rest/totvseai/standardmessage/v1/transactions/

Aviso

title	Atenção

No Protheus, cada grupo de empresas é um aplicativo diferente para o EAI. Desta maneira, cada grupo de empresas deve possuir um endereço REST diferente. Caso seja recebida uma requisição para um endereço cujo grupo de empresas é diferente do enviado, a seguinte mensagem será apresentada: O grupo de empresas do aplicativo não corresponde ao grupo de empresas deste serviço. Grupo recebido - (A). Grupo do serviço - (B) , onde A e B são respectivamente o grupo recebido na requisição e o grupo de empresas do endereço REST

Expandir

title	Cadastro de Adapters

Cadastro de Adapters:

O cadastro de adapters são rotinas responsáveis por realizar o processamento das mensagens enviadas e recebidas, possibilitando a inclusão, alteração e exclusão do adapter no Protheus.

Pré requisitos:

Para realizar o cadastro/configuração do adapter é necessário ter uma ROTA cadastrada, para cadastrá-la acesse o link: Cadastro de Rotas EAI.

No Configurador (SIFACFG), acesse Ambientes/Schedule/Adapter E.a.i
Efetue a Inclusão de uma nova rotina para os Adapters do sistema Protheus.
Configure a rotina do Adapter, de acordo com a tabela abaixo que já foram pré estabelecidos para a integração:

Mensagem única: Sim
Rotina: Nome do adapter
Mensagem: Nome da mensagem única que o Adapter EAI espera receber.
Descrição: Identificação da mensagem.
Envia: SIM (se envia a informação para VTEX) ou NÃO ( Se não envia nenhuma informação deste adapter para VTEX).
Recebe: SIM (se recebe a informação do VTEX) ou NÃO ( Se não recebe nenhuma informação deste adapter do VTEX).
Método: Síncrono/Assincrono
Operação: Todas
Canal de Envio: Para VTEX = 3-PAD.APP

Formato: JSON

Roteamento de mensagens: Informar a rota criada no cadastro de rota e se envia de acordo com a integração (ver tabela abaixo).

Exemplo de Cadastro:

Efetue a inclusão dos Adapters, conforme tabela abaixo:

Rotina Protheus

Mensagem

Descrição

Envia

Recebe

Método Protheus

Operação

Condição de envio

Canal de Envio

Versão

Alias

Rota

Formato

MATI410EC1

SalesOrder

Pedido de Venda

Não

Sim

Síncrono

Todas

PAD.APP

21.000

Rota VTEX

JSON

Importante

Informar a Rota de acordo com o Cadastro de Rotas EAI.

Cadastro de De/Para de Empresas:

No EAI Protheus deve-se cadastrar um relacionamento entre a Empresa e Filial do VTEX com uma existente no Protheus. Isto se deve ao fato de que, na Mensagem Única TOTVS

os valores trafegados na mensagem são sempre do sistema que enviou a mensagem, cabendo ao sistema receptor a tradução das informações trafegadas.

1. No Configurador (SIFACFG), acesse Ambientes/Schedule/Emp.Fil.Msg.Unica.
2. Cadastre De-Para de Empresas e Filiais e configure-os conforme os valores a seguir:

- Referência: VTEX
- Empresa : Código da Empresa VTEX a integrar.
- Filial: Código da Filial VTEX a integrar
- Grupo Emp. Protheus: Código da Empresa no Protheus a integrar com o sistema VTEX
- Fil. Protheus: Código da Filial no Protheus a integrar com o sistema VTEX
  
  Exemplo:
- Referência: VTEX
- Empresa : T3
- Filial: D MG 01
- Grupo Emp. Protheus: T3
- Fil. Protheus: D MG 01

Card

id	1
label	Configurações
effectType	fade

Expandir

title	Parâmetros Necessários

Não há.

Card

id	1
label	Validações e Processos
effectType	fade

Os pedidos de venda oriundos da "VTEX", não poderão ser alterados, através do Protheus.

O faturamento desses pedidos deverão ser faturados e transmitidos para o SEFAZ de maneira manual.

Para a integração com VTEX, a TES que será enviada, "NÃO", deverá gerar financeiro. Devido a integração financeira já ter sido integrada.

a Integração Financeira deverá ser feita pelo Adapter: LISTOFACCOUNTRECEIVABLEDOCUMENT

Para maiores detalhes: Integração Microsiga Protheus e VTEX via LISTOFACCOUNTRECEIVABLEDOCUMENT (EAI) - Integração Financeira - Integrações - TDN (totvs.com)

Card

id	1
label	Premissas Cadastrais
effectType	fade

Cadastro de Cliente:

Os campos deverão estar preenchidos

- Condições de pagamento

- Natureza

Card

id	1
label	Campos
effectType	fade

Header

Mensagen Padrão Header	Descrição	Valor	Tipo de Campo
Version		"2.005"	string
CompanyId	Codigo da Empresa Protheus		string
BranchId	Codigo da Filial Protheus		string
BusinessUnit	Código da Unidade de Negocio Protheus		string
GeneratedOn	Data da Geração (Formato UTC)	"2021-06-09T11:53:47Z"	string
Enterprise	Empresa Protheus		string
ProductVersion	Versão do Produto	Fixo: "12"	string
SourceApplication	Nome do Produto	Por exemplo: "VTEX"	string
ProductName	Nome do Produto	Por exemplo: "VTEX"	string
Transaction	Nome descrito nas rotas EAI	"Transaction": "RETAILSALES",	string
StandardVersion	Versão Standart	Fixo: "1.000"	string
UUID	Código UUID referente a mensagem	Deve ser Unico para cada integração: "5ca17002-3610-4158-a0bf-5c0e4f8e3fa2"	string
SubType	Subtipo	Fixo: "event"	string
Type	Tipo da Mensagem	Fixo: "BusinessMessage"	string
DeliveryType	Determina se a entrega será sincrona ou assincrona	sync async	string

Content

Mensagem Padrão - Content	Descrição	Valor	Tipo
CompanyId	Id da Empresa		string
Event		Upsert (Inserção / Alteração) Delete (Deleção)	string
BranchId	Id Filial		string
InternalId	Cód Interno do Sistema integrador		string
DocumentCode	Código Titulo Financeiro		string
CustomerVendorInternalId	Código Interno do Cliente		string
ECommerceOrder	Código Titulo Financeiro		string
TotalPrice	Valor total do Pedido		numeric
DiscountValue	Valor do desconto		numeric
IncreaseValue	Valor do Acréscimo		numeric
IssueDateDocument	Data de Emissão do Pedido de Venda	Utilizar formato UTC "2021-06-09T11:55:00"	string
FreightValue	Valor do Frete		numeric
CarrierCode	Codigo do Transportador - interno		string

Array "ListOfSaleItem":{

Mensagem Padrão - ListOfSaleItem	Descrição	Valor	Tipo
ItemCode	Codigo do Produto		string
Quantity	Qauntidade		Numeric
UnitPrice	Preço Unitário		Numeric
ItemPrice	Preço Total		Numeric
DiscountAmount	Desconto no item		Numeric
OperationCode	TES a ser utlizada		string
ItemReserveInternalId	Codigo da Reserva do Item		string

Array "ListOfSaleCondition":{

Mensagem Padrão - ListOfSaleCondition	Descrição	Valor	Tipo
PaymentValue
PaymentMethodCode
EftDocument

Card

id	1
label	Breve explicação dos campos
effectType	fade

Expandir

title	Campos Json

"Transaction": "SALESORDER", - Campo necessário para o correto direcionamento ao adapter EAI

"Event":"upsert", - Indicativo da operação (upsert - Inclusao ou alteração/DELETE - Exclusao do pedido)

"DeliveryType":"sync" - Indica se a operação será sincrona ou assincrona

"ItemCode":"VTEX001", - Codigo do produto

"OperationCode":"630", Código da TES

"CustomerVendorInternalId":"LOJ701_214_CLIENTE", - Código do Cliente

"ItemReserveInternalId":"" - Código da Reserva

"UUID":"LOJ701_214_SALESORDER001", - Identificado único da comunicação (Presente na tabela XX3, campo XX3_UUID)

Card

id	1
label	Mensagem JSON
effectType	fade

Mensagens JSON para a integração dos Pedidos de Venda

Expandir

title	Json Pedido de Venda - Inclusão

{
    "Header": {
        "Version": "21.005000",
        "CompanyId": "T1",
        "BranchId": "D MG 01",
        "BusinessUnit": "MG ",
        "GeneratedOn": "2021-06-09T11:53:47Z",
        "Enterprise": "T1",
        "ProductVersion": "12",
        "SourceApplication": "VTEX",
        "ProductName": "VTEX",
        "Transaction": "SALESORDER",
        "StandardVersion": "1.000",
        "UUID": "LOJ701_214_RETAILSALES_A81",
        "SubType": "event",
        "Type": "BusinessMessage",
        "DeliveryType": "sync"
    },
    "Content": {
        "Event": "upsert",
        "CompanyId": "T1",
        "BranchId": "D MG 01",
        "InternalId": "LOJ701_348",
        "DocumentCode": "701222",
        "CustomerVendorInternalId": "LOJ701_214_CLIENTE",
        "ECommerceOrder": "1133730662947-01",
        "TotalPrice": 160.00,
        "DiscountValue": 0.00,
        "IncreaseValue": 0,
        "IssueDateDocument": "2021-06-09T11:55:00",
        "FreightValue": 11.83,
        "CarrierCode": "",
        "ListOfSaleItem": {
            "SaleItem": [
                {
                    "ItemCode": "VTEX001",
                    "Quantity": 1.00,
                    "UnitPrice": 160.00,
                    "ItemPrice": 160.00,
                    "DiscountAmount": 10.00000,
                    "OperationCode": "630",
                    "ItemReserveInternalId": ""
                }
            ]
        },
        "ListOfSaleCondition": {
            "SaleCondition": [
                {
                    "PaymentValue": 75.00,
                    "PaymentMethodCode": "CC"
                },
                {
                    "PaymentValue": 75.00,
                    "PaymentMethodCode": "BOL"
                }
            ]
        }
    }
}

Expandir

title	Json Pedido de Venda - Alteração

{
    "Header": {
        "Version": "21.005000",
        "CompanyId": "T1",
        "BranchId": "D MG 01",
        "BusinessUnit": "MG ",
        "GeneratedOn": "2021-06-09T11:53:47Z",
        "Enterprise": "T1",
        "ProductVersion": "12",
        "SourceApplication": "VTEX",
        "ProductName": "VTEX",
        "Transaction": "SALESORDER",
        "StandardVersion": "1.000",
        "UUID": "LOJ701_214_RETAILSALES_A81",
        "SubType": "event",
        "Type": "BusinessMessage",
        "DeliveryType": "sync"
    },
    "Content": {
        "Event": "upsert",
        "CompanyId": "T1",
        "BranchId": "D MG 01",
        "InternalId": "LOJ701_348",
        "DocumentCode": "701222",
        "CustomerVendorInternalId": "LOJ701_214_CLIENTE",
        "ECommerceOrder": "1133730662947-01",
        "TotalPrice": 160.00,
        "DiscountValue": 0.00,
        "IncreaseValue": 0,
        "IssueDateDocument": "2021-06-09T11:55:00",
        "FreightValue": 11.83,
        "CarrierCode": "",
        "ListOfSaleItem": {
            "SaleItem": [
                {
                    "ItemCode": "VTEX001",
                    "Quantity": 1.00,
                    "UnitPrice": 160.00,
                    "ItemPrice": 160.00,
                    "DiscountAmount": 10.00000,
                    "OperationCode": "630",
                    "ItemReserveInternalId": ""
                }
            ]
        },
        "ListOfSaleCondition": {
            "SaleCondition": [
                {
                    "PaymentValue": 75.00,
                    "PaymentMethodCode": "CC"
                },
                {
                    "PaymentValue": 75.00,
                    "PaymentMethodCode": "BOL"
                }
            ]
        }
    }
}

Expandir

title	Json Pedido de Venda - Exclusão

{
    "Header": {
        "Version": "21.005000",
        "CompanyId": "T1",
        "BranchId": "D MG 01",
        "BusinessUnit": "MG ",
        "GeneratedOn": "2021-06-09T11:53:47Z",
        "Enterprise": "T1",
        "ProductVersion": "12",
        "SourceApplication": "VTEX",
        "ProductName": "VTEX",
        "Transaction": "SALESORDER",
        "StandardVersion": "1.000",
        "UUID": "LOJ701_214_RETAILSALES_A81",
        "SubType": "event",
        "Type": "BusinessMessage",
        "DeliveryType": "sync"
    },
    "Content": {
        "Event": "delete",
        "CompanyId": "T1",
        "BranchId": "D MG 01",
        "InternalId": "LOJ701_348",
        "DocumentCode": "701222",
        "CustomerVendorInternalId": "LOJ701_214_CLIENTE",
        "ECommerceOrder": "1133730662947-01",
        "TotalPrice": 160.00,
        "DiscountValue": 0.00,
        "IncreaseValue": 0,
        "IssueDateDocument": "2021-06-09T11:55:00",
        "FreightValue": 11.83,
        "CarrierCode": "",
        "ListOfSaleItem": {
            "SaleItem": [
                {
                    "ItemCode": "VTEX001",
                    "Quantity": 1.00,
                    "UnitPrice": 160.00,
                    "ItemPrice": 160.00,
                    "DiscountAmount": 10.00000,
                    "OperationCode": "630",
                    "ItemReserveInternalId": ""
                }
            ]
        },
        "ListOfSaleCondition": {
            "SaleCondition": [
                {
                    "PaymentValue": 75.00,
                    "PaymentMethodCode": "CC"
                },
                {
                    "PaymentValue": 75.00,
                    "PaymentMethodCode": "BOL"
                }
            ]
        }
    }
}

HTML

<!-- esconder o menu --> 


<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>

Páginas filhas

Versões comparadas

Versão antiga 54

Nova versão Atual

Chave

O caminho do serviço completo ficaria assim: http://127.0.0.1:8070/totvseai/standardmessage/v1/transactions/