ProtheusCargaEstoque (STATUS: PARCIAL)

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

Esta biblioteca organiza a integração de cargas de estoque do LINX para o Protheus, capturando movimentações pendentes e encaminhando cada registro para processamento em fila.

Capturador

Descrição Conceitual

Captura movimentações de estoque a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_CARGA_ESTOQUE e encaminha cada registro para processamento em fila. O fluxo suporta captura automática por agendador de tarefas, com limite de lote controlado por SELECT {{TOP}} (semáforo), e captura manual por chave no padrão cfilial-cLocal-cProduto.

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 item é registrado na fila de processamento.

Fonte

Destaque: a instrução SELECT {{TOP}} é usada para controlar a captura em lotes (semáforo). link: Conceito de Semáforo

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.
Conceito: semáforo (SELECT {{TOP}})

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.

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.

O payload é montado via getConteudo a partir do conteúdo da fila, com mapeamento direto dos campos. Ao final, registra o retorno e a situação na tabela de fila.

Estruturação de Dados

O payload enviado ao Protheus segue o schema definido no array $field da fila. Abaixo está o mapeamento oficial de origem → payload.

Campo no payload	Campo de origem
`cfilial`	`CFILIAL`
`cDtMovto`	`CDTMOVTO`
`cProduto`	`CPRODUTO`
`cLocal`	`CLOCAL`
`nQuant`	`NQUANT`
`nCusto`	`NCUSTO`

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: OSKWS012/MOVIMENTO
- Método HTTP: POST
- URL base: https://terrasde187161.protheus.cloudtotvs.com.br:4050/rest/
- Cabeçalhos: nenhum cabeçalho explícito informado na chamada (parâmetro vazio).

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), gera erro com JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Mapeamento de retorno: COD → code; MSG → message; errorCode → code; errorMessage → message.
- Condição de sucesso: quando code = S200, o item é finalizado como sucesso.
- Condição de erro: demais valores de code finalizam como erro.
- Consolidação de mensagem: quando existir detailedMessage, é concatenado à mensagem principal.

Tratamento de retorno

Persistência do resultado: o item processado é atualizado na tabela wosk_queue (base integrador), registrando retorno, mensagem, requisição, tempo e situação de processamento.

Situações utilizadas:
- 1: Em envio.
- 2: Sucesso.
- 4: Erro.

Encaminhamento em cenário de erro

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

Notificação

A notificação de erros consulta itens com falha na tabela wosk_queue para o serviço ProtheusCargaEstoque, ordena por data e prepara a mensagem para envio, extraindo apenas a parte relevante de erros de SQL Server quando aplicável e higienizando a mensagem de erro.

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 `wosk_queue` um item para cada registro retornado, com chave no padrão `cfilial-cLocal-cProduto`.	Itens 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 item correspondente na fila. Chave inválida quando `count(chave) < 3`.	Item 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 `wosk_queue` o retorno, mensagem e situação final.	Fila atualizada com situação final e detalhes de auditoria.