CONTEÚDO
01. VISÃO GERAL
O objetivo deste documento é explicar a integração do Protheus com o software Quírons através da troca de mensagens no formato JSON utilizando o padrão EAI (mensagem única) do Protheus.
02. O QUE É O QUÍRONS ?
O Quírons é uma solução SaaS voltada para SST (Saúde e Segurança do Trabalho) desenvolvida pela NG Informática, para maiores informações consulte a documentação no link https://quirons.com.br/.
03. ROTAS EAI
Para o Protheus enviar ou receber mensagens da integração é necessário que seja configurado uma rota EAI e para realizar esse cadastro deve acessar o modulo SIGACFG, depois navegar no menu em Ambiente > Schedule > Cadastro de Rotas EAI.
04. MENSAGENS ENVOLVIDAS
A integração com o Quírons utilizará as seguintes mensagens :
Mensagem | Rotina |
---|---|
ITEM | MATA010 |
UNITOFMEASURE | QIEA030 |
WAREHOUSE | AGRA045 |
STOCKTURNOVER | MATA241 |
STOCKLEVEL | MATA225 |
REQUEST | MATA105 |
A mensagem ITEM irá realizar o envio das informações do cadastro de produtos (MATA010) para o Quírons que irá consumir as seguintes tag's contidas na mensagem:
Tag | Conteúdo |
---|---|
CompanyId |
Empresa |
BranchId |
Filial |
InternalId | Código do Produto |
ItemDescription |
Descrição do Produto |
StandardCostPrice |
Custo unitário |
Active | Status do Produto Ativo/Inativo |
A mensagem UNITOFMEASURE irá enviar as informações do cadastro de unidade de medidas do Protheus para o Quírons que irá consumir as seguintes tag's:
Tag | Conteúdo |
---|---|
CompanyId |
Empresa |
BranchId |
Filial |
InternalId | Código do Produto |
Description |
Descrição da unidade de medida |
ShortName | Sigla |
A mensagem WAREHOUSE irá enviar as informações do cadastro de armazéns para o Quírons que irá consumir as seguintes tag's:
Tag | Conteúdo |
---|---|
CompanyId |
Empresa |
BranchId |
Filial |
InternalId | Código do Produto |
Description |
Descrição do armazém |
Active | Status do armazém |
A mensagem REQUEST contém as informações das solicitações de estoque enviadas pelo Quírons.
Tag | Conteúdo |
---|---|
CompanyId | Empresa |
BranchId | Filial |
InternalId | Código interno da requisição |
Type | Tipo da requisição |
RegisterDateTime | Data da Solicitação |
DeliveryDateTime | Data da Entrega |
ItemInternalId | Código interno do produto |
UnitOfMeasureInternalId |
Código interno da unidade de medida |
WarehouseInternalId |
Código interno do armazém |
Quantity |
Quantidade da solicitação |
Type
O conteúdo da tag Type será sempre fixo com o valor '001'
A mensagem STOCKTURNOVER contém as informações das movimentações de estoque dos tipos de movimento 'Requisição' e 'Devolução' que podem ser enviadas do Protheus para o Quírons e também enviadas do Quírons para o Protheus.
Tag | Conteúdo |
---|---|
CompanyId | Empresa |
BranchId | Filial |
InternalId |
Código interno da movimentação |
Type | Tipo da movimentação |
MovementTypeCode |
Código do tipo de movimento |
UnitPrice | Preço unitário do produto |
Quantity | Quantidade do produto |
ItemInternalId |
Código interno do produto |
UnitOfMeasureInternalId |
Código interno da unidade de medida |
WarehouseInternalId |
Código interno do armazém |
EmissionDate | Data da emissão |
Tipo de Movimento
Os códigos do tipo de movimento (MovementTypeCode) enviado do Quírons para o Protheus devem estar previamente cadastrados no cadastro de Tipos de Movimento (MATA230).
Códigos padrão Quirons:
Entrada: "399" - Movimento deve ser não valorizado.
Saída: "599" - Movimento deve ser não valorizado.
A mensagem STOCKLEVEL irá enviar o saldo atual de estoque dos produtos para o Quírons com as seguintes tag's:
Tag | Conteúdo |
---|---|
CompanyId |
Empresa |
BranchId |
Filial |
ItemInternalId |
Código do Produto |
WarehouseInternalId |
Código interno do armazém |
CurrentStockAmount |
Quantidade |
Importante
Para utilizar a mensagem StockLevel na integração entre Protheus x Quirons, é necessário cadastrar a versão "3.004" da mensagem no cadastro do Adapter.
Rotina SCHEDESTMG
Para que a mensagem STOCKLEVEL seja enviada a cada atualização de saldo de estoque é necessário configurar a rotina SCHEDESTMG no Schedule pelo Configurador do Protheus.
Para maiores informações sobre configuração do schedule consulte a documentação no link: DT Envio Ativo para Produtos com Estoque Alterado Desde o Último Envio
05. ADAPTER
O cadastro de adapter são rotinas responsáveis por realizar o processamento das mensagens enviadas e recebidas, possibilitando a inclusão, alteração e exclusão.
Para realizar o cadastro/configuração do adapter, antes é necessário ter uma ROTA cadastrada (Item 03). Após ter realizado o cadastro da rota, navegar no menu em Ambiente > Schedule > Adapter EAI (CFGA020).
Exemplo:
Obs.: Em todos adapters, no grid Roteamento de mensagens (para Mensagem Única com canal de envio EAI), selecionar a rota cadastrada conforme item 03 deste documento.
- Mensagem Única (XX4_UNMESS): 1-Sim
- Rotina (XX4_ROTINA): MATA010
- Mensagem (XX4_MODEL): ITEM
- Descrição (XX4_DESCRI): PRODUTO
- Envia (XX4_SENDER): Sim (Envia mensagem JSON para Quírons)
- Recebe (XX4_RECEIV): Sim (Recebe mensagem JSON do Quírons)
- Método (XX4_METHOD): Síncrono/Assíncrono
- Operação (XX4_TPOPER): 1-Todas
- Canal Envio (XX4_CHANEL): 3 - EAI - PAD.APP.
- Versão Envio (XX4_SNDVER): 4.005
- Formato (XX4_FORMAT): JSON
- Mensagem Única (XX4_UNMESS): 1-Sim
- Rotina (XX4_ROTINA): QIEA030
- Mensagem (XX4_MODEL): UNITOFMEASURE
- Descrição (XX4_DESCRI): UNIDADE DE MEDIDA
- Envia (XX4_SENDER): Sim (Envia mensagem JSON para Quírons)
- Recebe (XX4_RECEIV): Sim (Recebe mensagem JSON do Quírons)
- Método (XX4_METHOD): Síncrono/Assíncrono
- Operação (XX4_TPOPER): 1-Todas
- Canal Envio (XX4_CHANEL): 3 - EAI - PAD.APP.
- Versão Envio (XX4_SNDVER): 2.002
- Formato (XX4_FORMAT): JSON
- Mensagem Única (XX4_UNMESS): 1-Sim
- Rotina (XX4_ROTINA): AGRA045
- Mensagem (XX4_MODEL): WAREHOUSE
- Descrição (XX4_DESCRI): LOCAIS DE ESTOQUE
- Envia (XX4_SENDER): Sim (Envia mensagem JSON para Quírons)
- Recebe (XX4_RECEIV): Sim (Recebe mensagem JSON do Quírons)
- Método (XX4_METHOD): Síncrono/Assíncrono
- Operação (XX4_TPOPER): 1-Todas
- Canal Envio (XX4_CHANEL): 3 - EAI - PAD.APP.
- Versão Envio (XX4_SNDVER): 1.000
- Formato (XX4_FORMAT): JSON
- Mensagem Única (XX4_UNMESS): 1-Sim
- Rotina (XX4_ROTINA): MATA225
- Mensagem (XX4_MODEL): STOCKLEVEL
- Descrição (XX4_DESCRI): SALDOS EM ESTOQUE
- Envia (XX4_SENDER): Sim (Envia mensagem JSON para Quírons)
- Recebe (XX4_RECEIV): Não (Não recebe mensagem JSON do Quírons)
- Método (XX4_METHOD): Síncrono/Assíncrono
- Operação (XX4_TPOPER): 1-Todas
- Canal Envio (XX4_CHANEL): 3 - EAI - PAD.APP.
- Versão Envio (XX4_SNDVER): 3.004
- Formato (XX4_FORMAT): JSON
- Mensagem Única (XX4_UNMESS): 1-Sim
- Rotina (XX4_ROTINA): MATA105
- Mensagem (XX4_MODEL): REQUEST
- Descrição (XX4_DESCRI): SOLICITACAO AO ARMAZEM
- Envia (XX4_SENDER): Sim (Envia mensagem JSON para Quírons)
- Recebe (XX4_RECEIV): Sim (Recebe mensagem JSON do Quírons)
- Método (XX4_METHOD): Síncrono/Assíncrono
- Operação (XX4_TPOPER): 1-Todas
- Canal Envio (XX4_CHANEL): 3 - EAI - PAD.APP.
- Versão Envio (XX4_SNDVER): 1.009
- Formato (XX4_FORMAT): JSON
- Mensagem Única (XX4_UNMESS): 1-Sim
- Rotina (XX4_ROTINA): MATA241
- Mensagem (XX4_MODEL): STOCKTURNOVER
- Descrição (XX4_DESCRI): MOVIMENTACOES INTERNAS MULT.
- Envia (XX4_SENDER): Sim (Envia mensagem JSON para Quírons)
- Recebe (XX4_RECEIV): Sim (Recebe mensagem JSON do Quírons)
- Método (XX4_METHOD): Síncrono/Assíncrono
- Operação (XX4_TPOPER): 1-Todas
- Canal Envio (XX4_CHANEL): 3 - EAI - PAD.APP.
- Versão Envio (XX4_SNDVER): 1.000
- Formato (XX4_FORMAT): JSON
Para que o envio das mensagens assíncronas seja realizado, é necessário efetuar o cadastro das rotinas FWEAISEND/FWEAI, no Schedule Protheus.
- FWEAISEND: Esta rotina é exclusiva para o envio das mensagens da fila do EAI. O agendamento desta rotina é realizado por Empresa cadastrada no sistema. No envio da mensagem, um canal de comunicação é aberto com o webservice do produto integrado, e esta comunicação é encerrada após o recebimento da mensagem de retorno (no caso das Mensagens Única TOTVS, após o recebimento da ReceiptMessage, indicando que que o processo ocorreu corretamente) ou por timeout (mensagem com status de falha).
- FWEAI: Esta rotina de envio e recebimento de mensagens do EAI Protheus. Quando agendada, esta rotina executa dois passos.
- Inicia o processamento das mensagens recebidas na fila do EAI Protheus.
- Inicia o envio das mensagens que estão na fila do EAI Protheus.
Antes de efetuar o cadastro das rotinas FWEAISEND/FWEAI, é necessário a inclusão dos Agent.
- AGENT: Este é o componente que gerencia as execuções e distribui as tarefas para que as Executes configuradas que estão disponíveis no momento. Os Agents podem estar localizados em servidores diferentes, possibilitando o balanceamento da carga de execuções.
Inclusão das rotinas FWEAIRECE/FWEAISEND no agendamento
- Navegar no menu em Ambiente > Schedule > Schedule (CFGA010).
- Na barra lateral, acessar Schedule > Agendamentos > Cadastro
- No grid Detalhes, clicar no primeiro ícone para inclusão.
- Código: Valor sequencial que representa o identificador único desse agente no sistema. Ele é preenchido automaticamente;
Usuário: Usuário do Protheus que será utilizado para inicializar o processo;
Nome do usuário: Nome do usuário no sistema. É preenchido à partir do Usuário selecionado no campo anterior;
Rotina: FWEAI (Rotina envio e recebimento de mensagens do EAI Protheus) / FWEAISEND (Rotina recebimento de mensagens do EAI Protheus).
Data: Qual a data da execução do agendamento.
Hora: Qual a hora em que a função será executada.
Observe a opção “Recorrência” na barra de opções permite que você especifique a execução em intervalos regulares (diariamente, mensalmente, anual, a cada X horas…)
-
- Ambiente: Qual o ambiente que será inicializado na execução;
Empresa/Filial: Qual empresa e filial será aberta no momento da execução. Novamente, repare que esses campos não invalidam funcionalidades que abram e utilizem um ambiente diferente;
Módulo: Qual o módulo do Protheus que será utilizado na execução do agendamento. Essa informação é importante pois interfere na forma como o Protheus irá consumir as licenças disponíveis para a execução do job;
Nome do Módulo: O nome do módulo selecionado no campo anterior e é preenchido automaticamente;
Habilitada: Flag que determina se a execução do agendamento está habilitada ou não;
- Descrição: Descrição livre sobre o agendamento;
06. DE/PARA EMPRESAS
Em uma integração entre sistemas é comum os sistemas terem códigos diferentes, neste caso é muito importante ter um 'De/Para" (XXD), para que seja mapeado e retornado o valor interno de um determinado registro da tabela informada no cadastro de De/Para.
Para realizar cadastro, deve acessar o modulo SIGACFG, depois navegar no menu em Ambiente > Schedule > Emp.Filial Mensagem Única (APCFG050).
- Referência: QUIRONS (SEM ACENTO).
- Empresa : Código da Empresa (Configurar com base nas informações do Protheus)
- Filial: Código da Filial (Configurar com base nas informações do Protheus).
- Grupo Emp. Protheus: Código da Empresa no Protheus a integrar com o sistema Quírons.
- Fil. Protheus: Código da Filial no Protheus a integrar com o sistema Quírons.
Exemplo:
- Referência: QUIRONS
- Empresa : T1
- Filial: D MG 01
- Grupo Emp. Protheus: T1
- Fil. Protheus: D MG 01
07. OBSERVAÇÕES
Para realizar integração com o Quírons na Baixa da Requisição (MATA185), nos parâmetros (F12) a primeira pergunta deve estar conforme imagem abaixo.