ProtheusTransportadora (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_transportadora
Data	27/02/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
27/02/2026	1.0	Maykon	Criação da documentação técnica do processo ProtheusTransportadora.

Descrição

Esta biblioteca integra os cadastros de transportadoras do LINX para o Protheus, garantindo captura consistente e envio com validação de retorno.

Capturador

Descrição Conceitual

Permite a captura manual (por lista de códigos) e a captura automática (por agendador de tarefas) das transportadoras pendentes de integração, consultando a origem e registrando os itens para processamento assíncrono.

A captura automática segue processamento cronológico (ordenação/paginação por data) para priorizar registros mais antigos e manter continuidade por posição; link conceitual: Processamento cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_TRANSPORTADORAS.

Consulta utilizada na captura automática (WHERE e paginação construídos dinamicamente conforme posição e configuração de limite):

SELECT
    CODIGO,
    NOME,
    NOME_REDUZ,
    ENDERECO,
    BAIRRO,
    COMPLEMENTO,
    UF,
    COD_MUNICIPIO_IBGE,
    CEP,
    DDI,
    DDD,
    TELEFONE,
    CGC,
    INSCRICAO,
    EMAIL,
    COD_PAIS_BC,
    A4_MSBLQL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_TRANSPORTADORAS
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <OFFSET> ROWS FETCH NEXT <LIMITE> ROWS ONLY

Consulta utilizada na captura manual (lista de códigos e WHERE construído dinamicamente):

SELECT
    CODIGO,
    NOME,
    NOME_REDUZ,
    ENDERECO,
    BAIRRO,
    COMPLEMENTO,
    UF,
    COD_MUNICIPIO_IBGE,
    CEP,
    DDI,
    DDD,
    TELEFONE,
    CGC,
    INSCRICAO,
    EMAIL,
    COD_PAIS_BC,
    A4_MSBLQL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_TRANSPORTADORAS
WHERE
    CODIGO IN ('<CODIGO_1>','<CODIGO_2>')

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_TRANSPORTADORAS para obter o registro atual de transportadora (campo-chave CODIGO) e encaminhar para processamento assíncrono.

- Leitura auxiliar de chaves com falha (checagem): consulta a tabela wosk_capturar filtrando por ProtheusTransportadora e situação igual erro, retornando até 500 chaves para suporte operacional.

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

{
  "A4_COD": "",
  "A4_NOME": "",
  "A4_NREDUZ": "",
  "A4_END": "",
  "A4_BAIRRO": "",
  "A4_COMPLEM": "",
  "A4_EST": "",
  "A4_COD_MUN": "",
  "A4_CEP": "",
  "A4_DDI": "",
  "A4_DDD": "",
  "A4_TEL": "",
  "A4_CGC": "",
  "A4_INSEST": "",
  "A4_EMAIL": "",
  "A4_CODPAIS": "",
  "A4_MSBLQL": ""
}

Tratamento de Dados

Quando algum campo não estiver disponível no registro atual, o valor é preenchido de forma consistente (ex.: vazio), garantindo que o envio mantenha o formato esperado pelo Protheus.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: transportadora
- Método HTTP: POST
- Cabeçalhos: nenhum cabeçalho explícito informado na chamada

Tratamento de retorno

Ausência de resposta: registra erro com mensagem de “não houve resposta” e finaliza o item como falha.

Resposta inválida/inesperada: se o retorno não puder ser interpretado como estrutura contendo Mensagem, registra erro de decodificação e finaliza como falha.

Indicadores de erro: finaliza como falha quando houver code no retorno ou quando Mensagem for ERRO. Quando disponível, utiliza Mensagem Detalhada como mensagem final.

Sucesso: quando não houver indicadores de erro, finaliza como sucesso e persiste o retorno para auditoria.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada e a situação final (sucesso/erro). O tempo de processamento é registrado para acompanhamento operacional.

Encaminhamento em cenário de erro

Quando ocorre erro na integração (ausência de resposta, resposta inválida ou retorno com indicador de falha), o item é finalizado como erro e permanece registrado em wosk_queue com detalhes de mensagem e retorno, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

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_TRANSPORTADORAS com ordenação por DATA_PARA_TRANSFERENCIA e paginação, deve manter a continuidade por posição persistida em wosk_monitor (evento, offset, chave_posicao, data_posicao).	Posição atualizada na tabela wosk_monitor e itens pendentes registrados para processamento assíncrono.
Capturador	Captura manual por código	Ao informar uma lista de CODIGO, deve consultar a view filtrando por CODIGO IN (...) e registrar cada item correspondente para processamento.	Itens pendentes registrados para processamento, associados ao código da transportadora.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusTransportadora), deve montar payload conforme $field (campos A4_*) e realizar a integração com o recurso transportadora, registrando o retorno e a mensagem final.	Item atualizado em wosk_queue com retorno/mensagem e situação final coerente (sucesso quando não houver erro; erro quando houver ausência de resposta, resposta inválida, code ou Mensagem = ERRO).