ProtheusClienteFull (STATUS: REVISADO)

Documentação Técnica

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

Histórico de Versões

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

Descrição

Este serviço organiza a integração de cadastros de clientes do LINX para o Protheus, garantindo que cada cliente seja identificado, preparado e encaminhado para envio.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais clientes específicos mediante a informação das chaves, com validação obrigatória do formato no padrão A1_LOJA-A1_COD. 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_CLIENTES_FULL, consultada com projeção predefinida, sendo o filtro por loja (A1_LOJA) e código do cliente (A1_COD) acrescentado dinamicamente durante a execução. Para cada registro retornado, é gerada a chave de fila no mesmo padrão e o item é devidamente registrado para processamento em fila.

Fonte

Consulta principal (filtro por A1_LOJA e A1_COD):

SELECT
    A1_COD,
    A1_LOJA,
    CGC_CPF,
    NOME,
    PESSOA,
    NOME_REDUZ,
    ENDERECO,
    BAIRRO,
    COMPLEMENTO,
    TIPO,
    UF,
    COD_MUNICIPIO_IBGE,
    CEP,
    DDI,
    DDD,
    TELEFONE,
    CONTATO,
    A1_PFISICA,
    A1_INSCR,
    INSC_MUNICIPAL,
    DATA_NASC,
    EMAIL,
    COD_PAIS_SISCOMEX,
    COD_PAIS_BC,
    A1_CONTA,
    A1_CONTRIB,
    A1_TPESSOA,
    A1_SUFRAMA,
    A1_CALCSUF,
    A1_CODMUN,
    STATUS,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL
WHERE
    A1_LOJA = '<A1_LOJA>'
    AND A1_COD = '<A1_COD>'

Operações com Dados

Leitura: Consulta da view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL.

Validação (captura manual): exige chave no padrão A1_LOJA-A1_COD; em formato inválido, o processo é interrompido com erro de chave inválida.

Persistência: Grava itens pendentes na Fila de Processamento, com chave A1_LOJA-A1_COD.

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

Tratamento de Dados

Transformações aplicadas no payload antes do envio:

Integração com o Protheus

Exemplo de payload enviado (JSON):

{
    "A1_COD": "157612267",
    "A1_LOJA": "03",
    "A1_CGC": "15763336703",
    "A1_NOME": "TESTE",
    "A1_PESSOA": "F",
    "A1_NREDUZ": "TESTE",
    "A1_END": "RUA SILVIA POZZANO, 2820",
    "A1_BAIRRO": "RECREIO DOS BANDEIRANTES",
    "A1_COMPLEM": "B1 AP 811,",
    "A1_TIPO": "F",
    "A1_EST": "RJ",
    "A1_COD_MUN": "02257",
    "A1_CEP": "22790622",
    "A1_DDI": "",
    "A1_DDD": "99",
    "A1_TEL": "993207988",
    "A1_CONTATO": "TESTE",
    "A1_PFISICA": "",
    "A1_INSCR": "ISENTO",
    "A1_INSCRM": "",
    "A1_DTNASC": "06/05/9999",
    "A1_EMAIL": "TESTE",
    "A1_PAIS": "105",
    "A1_CODPAIS": "01099",
    "A1_CONTA": "220301040199",
    "A1_CONTRIB": "2",
    "A1_TPESSOA": "",
    "A1_SUFRAMA": "",
    "A1_CALCSUF": "",
    "A1_CODMUN": "",
    "A1_MSBLQL": "2"
}

Tratamento de retorno

Ausência de resposta: Se não houver retorno, o item é finalizado com erro e a mensagem indica falta de resposta.

Resposta inválida/inesperada: Se o retorno não for um objeto com o campo Mensagem, o item é finalizado com erro e a mensagem indica falha na decodificação.

Falha: Quando o retorno traz Mensagem igual a ERRO ou quando existe o campo code, o item é marcado como erro.

Sucesso: Quando não há indicador de erro, o processo registra o cliente como integrado e grava o retorno na fila.

Encaminhamento em cenário de erro

Quando o Protheus retorna erro, o fluxo tenta encaminhar o mesmo cliente para o serviço ProtheusClientePadrao, solicitando a captura do cliente pela mesma chave A1_LOJA-A1_COD.

Se for capturado (serviço ProtheusClientePadrao), ou já existir, o registro atual é removido do serviço para evitar duplicidade de integração.

 

Rotinas Inteligentes

setProtheusClienteIntegrado: após confirmação de sucesso da integração, reinicia os processos que estão suspensos marcados com "ProtheusCliente" vinculados com o registro atual.
link: Cliente Integrado

Notificação

Existe um mecanismo de notificação que identifica os itens com erro na fila de processamento, ordenando por data de processamento e enviando em um relatório a destinatários pré-definidos.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura e enfileiramento	Ao informar uma chave válida no padrão A1_LOJA-A1_COD, deve consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL e registrar o item correspondente na fila de processamento.	Item pendente registrado na fila, pronto para processamento, com chave consistente.
Fila de Processamento	Integração com Protheus	Ao processar um registro pendente, deve estruturar o payload conforme estrutura definida, aplicar as transformações necessárias e chamar o recurso /rest/cliente no Protheus via POST com o cabeçalho tenantId.	Fila atualizada com situação final e detalhes para auditoria; em sucesso, cliente marcado como integrado.