ProtheusCargaEstoque (STATUS: REVISADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_carga_estoque
Data	03/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
03/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo ProtheusCargaEstoque.

Descrição

Este serviço integra cargas de estoque do LINX para o Protheus, capturando movimentações pendentes e encaminhando cada registro para processamento assíncrono.

Capturador

Descrição Conceitual

Captura

movimentações de estoque

Permite a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_CARGA_ESTOQUE e encaminha cada registro para processamento na fila. O fluxo suporta captura automática por agendador de tarefas, com limite de lote controlado por SELECT {{TOP}} (semáforo), e captura manual porde chaveum ou mais clientes específicos mediante a informação das chaves, com validação obrigatória do formato no padrão cfilial-cLocal-cProduto.
 Caso a chave informada esteja fora do padrão, o processo é imediatamente interrompido com erro de chave inválida, garantindo integridade e previsibilidade no fluxo.

A origem dos dados é a view WOSK_SERVICO_ENVIA_PROTHEUS_CARGA_ESTOQUE, consultada com projeção predefinida. O filtro WHERE CAPTURADO_ISNAPP = 0 é aplicado na captura automática. Para cada registro retornado, é gerada a chave de fila no padrão cfilial-cLocal-cProduto e o registro é registrado na fila de processamento.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CARGA_ESTOQUE.

Operações com Dados

Leitura: consulta a origem com limitação dinâmica por SELECT {{TOP}}, que funciona como controle de volume por execução.
link: Conceito de Semáforo

Consulta usada na captura por lote (limite substitui {{TOP}}):

SELECT {{TOP}}
    CFILIAL AS cfilial,
    CDTMOVTO AS cDtMovto,
    CPRODUTO AS cProduto,
    CLOCAL AS cLocal,
    NQUANT AS nQuant,
    NCUSTO AS nCusto,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CARGA_ESTOQUE (NOLOCK)

Filtro aplicado no fluxo:

... WHERE CAPTURADO_ISNAPP = 0

Captura manual: o filtro WHERE é montado dinamicamente a partir da chave, restringindo por CFILIAL, CLOCAL e CPRODUTO. Chave inválida quando count(chave) < 3.

 

Operações com Dados

Leitura: consulta a origem com limitação dinâmica por SELECT {{TOP}}, que funciona como controle de volume por execução.
Consulta usada na captura por lote (limite substitui {{TOP}}):
link: Conceito de Semáforo

Fila de Processamento

Descrição Conceitual

A fila recupera um registro pendente e utiliza o conteúdo do registro como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização e realiza a chamada ao Protheus.

 

Estruturação de Dados

Exemplo de payload enviado

{
  "cfilial": "",
  "cDtMovto": "",
  "cProduto": "",
  "cLocal": "",
  "nQuant": 0,
  "nCusto": 0
}

Tratamento de Dados

Padronização numérica (setNumeric)
- nQuant, nCusto: normalizados com o padrão do setNumeric(...).

 

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: /rest/OSKWS012/MOVIMENTO
- Método HTTP: POST
- URL base: https://terrasde187161.protheus.cloudtotvs.com.br:4050/rest/

Exemplo de payload enviado

{
  "cfilial": "",
  "cDtMovto": "",
  "cProduto": "",
  "cLocal": "",
  "nQuant": 0,
  "nCusto": 0
}

 

 

Tratamento de retorno

Ausência de resposta: gera erro com mensagem JSON: NÃO HOUVE RESPOSTA.

Resposta inválida/inesperada: quando code estiver vazio (após mapeamento de COD/errorCode) ou errorCode), gera erro com JSON:JSON "NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
RESPOSTA".

MapeamentoCOD, deerrorCode: retorno:mapeados CODpara → code; MSG → message; errorCode → code; errorMessage → message.
code.

CondiçãoMSG, deerrorMessage: sucesso:mapeados quandopara message.

• code = S200,S200: finaliza o registro é finalizado como sucesso.
  

Condiçã

• code ≠ S200: finaliza o de erro: demais valores de code finalizamregistro como erro.
  

Consolidação de mensagem:detailedMessage: quando existir detailedMessage,existente, é concatenado à mensagem principal.

Persistência

do resultado: o registro processado é atualizado na tabela Fila de Processamento (base integrador), registrando retorno, mensagem, requisição, tempo e situação de processamento.

Encaminhamento em cenário de erro

Quando ocorre falha no envio ou na validação da resposta, o registro permanece como erro com mensagem registrada para correção e reprocessamento.

 

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura e enfileiramento	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_CARGA_ESTOQUE com CAPTURADO_ISNAPP = 0 e limite via SELECT {{TOP}}, deve registrar na Fila de Processamento um registro para cada registro retornado, com chave no padrão cfilial-cLocal-cProduto.	Registros pendentes registrados na fila, prontos para processamento.
Capturador	Captura manual	Ao informar uma chave válida no padrão cfilial-cLocal-cProduto, deve consultar a view e registrar o registro correspondente na fila. Chave inválida quando count(chave) < 3.	Registro pendente registrado na fila ou erro de chave inválida.
Fila de Processamento	Integração e persistência do retorno	Após enviar ao Protheus (POST no recurso OSKWS012/MOVIMENTO), deve validar a resposta (sucesso quando code = S200) e registrar em Fila de Processamento o retorno, mensagem e situação final.	Fila atualizada com situação final e detalhes de auditoria.