ProtheusCondicaoPagamento (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_condicao_pagamento
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 ProtheusCondicaoPagamento.

Descrição

Esta biblioteca organiza a integração de condições de pagamento do LINX para o Protheus, capturando registros pendentes e encaminhando cada um para processamento em fila.

Capturador

Descrição Conceitual

Captura condições de pagamento a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_COND_PGTO e encaminha cada registro para processamento em fila. A captura suporta processamento cronológico (filtro por DATA_PARA_TRANSFERENCIA, ordenação e paginação com OFFSET/FETCH NEXT), e também permite captura manual por um ou mais códigos (CODIGO IN (...)).

A origem dos dados é a view WOSK_SERVICO_ENVIA_PROTHEUS_COND_PGTO, consultada com projeção predefinida. O filtro WHERE DATA_PARA_TRANSFERENCIA >= '...' e a ordenação por DATA_PARA_TRANSFERENCIA ASC com OFFSET/FETCH NEXT são aplicados na captura automática. Para cada registro retornado, a chave de fila é o próprio CODIGO e o item é registrado na fila de processamento.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_COND_PGTO.

Operações com Dados

Processamento cronológico (ordenação/paginação por data): a captura consulta registros com filtro por DATA_PARA_TRANSFERENCIA, ordena por DATA_PARA_TRANSFERENCIA ASC e pagina com OFFSET/FETCH NEXT.
link: Cronológico

Consulta base da fonte (projeção completa):

SELECT
    CODIGO,
    TIPO,
    COND_PGTO,
    DESC_COND_PGTO,
    DDD,
    MSBLQL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_COND_PGTO

Consulta cronológica por lote (string dinâmica):

SELECT
    CODIGO,
    TIPO,
    COND_PGTO,
    DESC_COND_PGTO,
    DDD,
    MSBLQL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_COND_PGTO
WHERE
    DATA_PARA_TRANSFERENCIA >= '{DATA_PARA_TRANSFERENCIA}'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    {OFFSET} ROWS
FETCH NEXT
    {TOP} ROWS ONLY

Captura manual: o filtro WHERE CODIGO IN ('...', '...') é montado dinamicamente a partir da lista de códigos informados.

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 dos campos conforme o schema $field. Não há transformações numéricas adicionais. 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.

Exemplo de payload enviado

{
  "E4_CODIGO": "",
  "E4_TIPO": "",
  "E4_COND": "",
  "E4_DESCRI": "",
  "E4_DDD": "",
  "E4_MSBLQL": ""
}

Tratamento de Dados

O payload é montado via getConteudo sem transformações numéricas ou de padronização adicionais.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: condicaopgto
- Método HTTP: padrão do integrador (não especificado explicitamente no código)
- Cabeçalhos: nenhum cabeçalho explícito informado na chamada.

Tratamento de retorno
- Ausência de resposta: gera erro com mensagem JSON: NÃO HOUVE RESPOSTA.
- Resposta inválida/inesperada: se não for array ou não contiver Mensagem, gera erro com JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Condição de erro: quando existir code na resposta ou quando Mensagem = ERRO, o processamento é marcado como falha.
- Condição de sucesso: quando não houver code e Mensagem for diferente de ERRO, o item é finalizado como sucesso.
- Mensagem detalhada: quando presente, Mensagem Detalhada é utilizada como base da mensagem final.

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

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura cronológica e encaminhamento	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_COND_PGTO com filtro DATA_PARA_TRANSFERENCIA >= ..., ordenar por DATA_PARA_TRANSFERENCIA ASC e paginar com OFFSET/FETCH NEXT, deve registrar na wosk_queue um item para cada registro retornado, com chave igual ao CODIGO.	Itens pendentes registrados na fila, prontos para processamento.
Capturador	Captura manual	Ao informar um ou mais códigos, deve consultar a view com WHERE CODIGO IN (...) e registrar cada item correspondente na fila.	Itens pendentes registrados na fila para os códigos informados.
Fila de Processamento	Integração e persistência do retorno	Após enviar ao Protheus (recurso condicaopgto), deve validar a resposta (sucesso quando ausência de code e Mensagem diferente de ERRO) e registrar em wosk_queue o retorno, mensagem e situação final.	Fila atualizada com situação final e detalhes de auditoria.