ProtheusMovimentoContabil (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_movimento_contabil
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	Criação da documentação técnica do processo ProtheusMovimentoContabil.

Descrição

Esta biblioteca organiza o envio de movimentos contábeis do LINX para o Protheus, garantindo captura por chave ou por data, montagem das linhas do lançamento e registro do resultado da integração.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais movimentos contábeis por chave (ORIGEM), consultando a origem e carregando as linhas do lançamento antes de registrar o item para processamento assíncrono.

A captura por data consulta a origem filtrando por DATA_DIGITACAO no intervalo do dia (BETWEEN dataInicio AND dataFim), ordenando por DATA_DIGITACAO ASC e paginando por OFFSET/FETCH, caracterizando processamento cronológico (ordenação/paginação por data); link conceitual: Processamento cronológico. A execução periódica pode ser acionada por agendador de tarefas.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL e view WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL_LINHAS.

Consulta utilizada na captura por data (WHERE e paginação construídos dinamicamente conforme posição e limite configurado):

SELECT
    FILIAL,
    DTLANC,
    ORIGEM,
    DATA_DIGITACAO
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL (NOLOCK)
WHERE
    DATA_DIGITACAO BETWEEN '<dataInicio>' AND '<dataFim>'
ORDER BY
    DATA_DIGITACAO ASC
OFFSET
    <offset> ROWS FETCH NEXT <top> ROWS ONLY

Consulta utilizada na captura manual (WHERE construído dinamicamente a partir das chaves informadas):

SELECT
    FILIAL,
    DTLANC,
    ORIGEM,
    DATA_DIGITACAO
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL (NOLOCK)
WHERE
    ORIGEM IN ('<chave1>', '<chave2>', ...)

Consulta utilizada para carregar as linhas do lançamento (WHERE construído dinamicamente a partir da ORIGEM):

SELECT
    DEBITO,
    CREDITO,
    CCD,
    CCC,
    VALOR,
    HISTORICO,
    LANCAMENTO,
    ITEMDEB,
    ITEMCRED,
    CLASSEDEB,
    CLASSECRED,
    DATA_DIGITACAO
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL_LINHAS (NOLOCK)
WHERE
    LANCAMENTO = '<ORIGEM>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL para obter o registro atual do movimento contábil e construir o identificador de processamento com base em ORIGEM.

- Carregamento de linhas: para cada registro atual, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL_LINHAS filtrando por LANCAMENTO = ORIGEM e agrega os itens retornados no campo linhas, formando o conjunto completo (cabeçalho + linhas) para integração.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusMovimentoContabil, aplicado na paginação da consulta (FETCH NEXT <top>).

- Registro para processamento: cada movimento contábil capturado é persistido como pendência na tabela wosk_queue sob o serviço ProtheusMovimentoContabil, com o conteúdo vindo da origem (incluindo linhas) para processamento assíncrono.

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

{
  "filial": "",
  "dtlanc": "",
  "origem": "",
  "linhas": [
    {
      "debito": "",
      "credito": "",
      "ccd": "",
      "ccc": "",
      "itemdeb": "",
      "itemcred": "",
      "classedeb": "",
      "classecred": "",
      "valor": 0,
      "historico": ""
    }
  ]
}

Tratamento de Dados

- Normalização de data: dtlanc formatado para Ymd via setDateTime().

- Normalização numérica (linhas): valor em cada item de linhas via setNumeric().

- Cabeçalho de integração: o header tenantId é gerado como <UF>,<FILIAL>, em que <UF> é o prefixo de 2 caracteres de filial.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtblinx/lctocontabil
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <UF>,<FILIAL>

Tratamento de retorno

Ausência de resposta: registra falha com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como erro (situacao = 4).

Resposta inválida/inesperada: quando não for possível obter Mensagem ou o retorno não for array, registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Indicadores de sucesso/erro: considera erro quando Mensagem for igual a ERRO ou quando code estiver presente (não vazio). Em ambos os casos, situacao = 4. Sucesso quando Mensagem for OK e code estiver vazio ou ausente, finalizando com situacao = 2.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada (priorizando Mensagem Detalhada quando disponível), a situação final (situacao = 2 em sucesso, situacao = 4 em erro) e o tempo de processamento.

Encaminhamento em cenário de erro

Quando houver falha por ausência de resposta, retorno inválido, Mensagem igual a ERRO ou presença de code, o item permanece registrado em wosk_queue com detalhes do retorno e mensagem para acompanhamento e eventual reprocessamento.

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura cronológica e controle de posição	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL com filtro por DATA_DIGITACAO no intervalo do dia, ordenação ascendente e paginação por OFFSET/FETCH, deve manter a continuidade por posição persistida em wosk_monitor (evento, offset, chave_posicao, data_posicao, filtro).	Posição atualizada em wosk_monitor e itens pendentes registrados para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma ou mais chaves (ORIGEM), deve consultar a origem filtrando por ORIGEM IN (...) e montar linhas a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_MOVIMENTO_CONTABIL_LINHAS antes de registrar o item para processamento.	Item pendente registrado com linhas carregadas quando a chave for válida.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusMovimentoContabil), deve enviar requisição POST para o recurso rtblinx/lctocontabil com o payload completo (cabeçalho + linhas, com dtlanc em Ymd e valor normalizado) e registrar retorno, mensagem e situação final.	Item atualizado em wosk_queue com retorno/mensagem e situação final coerente (sucesso quando Mensagem for OK e code estiver vazio ou ausente; erro quando não houver resposta, não houver Mensagem ou Mensagem for ERRO ou code estiver presente).