ProtheusClienteFull (STATUS: PARCIAL)

DocumentaçãDocumentação TéTécnica

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

HistóHistórico de VersõVersões

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

DescriçãDescrição

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

Capturador

DescriçãDescrição Conceitual

Permite a captura manual de um ou mais clientes especíespecíficos mediante a informaçãinformação das chaves, com validaçãvalidação obrigatóobrigatória do formato no padrãpadrão A1_LOJA-A1_COD. Caso a chave informada esteja fora do padrãpadrão, o processo éé imediatamente interrompido com erro de chave inváinválida, garantindo integridade e previsibilidade no fluxo.

A origem dos dados éé a view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL, consultada com projeçãprojeção predefinida, sendo o filtro por loja (A1_LOJA) e cócódigo do cliente (A1_COD) acrescentado dinamicamente durante a execuçãexecução. Para cada registro retornado, éé gerada a chave de fila no mesmo padrãpadrão e o item éé devidamente registrado para processamento em fila.

Fonte

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çõOperações com Dados

Leitura: Consulta da view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL.

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

Fila de Processamento

DescriçãDescrição Conceitual

EstruturaçãEstruturação de Dados

O conteúconteúdo do item éé ajustado para o padrãpadrão esperado pelo Protheus (campos A1_*).

Mapeamento de campos aplicado:

Tratamento de Dados

ApóApós o mapeamento, sãsão aplicadas os seguintes tratamentos no payload:

IntegraçãIntegração com o Protheus

Exemplo de payload enviado: (valores ilustrativos)

{
    "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êAusência de resposta: Se nãnão houver retorno, o item éé finalizado com erro e a mensagem indica falta de resposta.

Resposta inváinválida/inesperada: Se o retorno nãnão for um objeto com o campo Mensagem, o item éé finalizado com erro e a mensagem indica falha na decodificaçã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ãnão háhá indicador de erro, o processo registra o cliente como integrado e grava o retorno na fila.

Encaminhamento em cenácenário de erro

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

Se a captura for confirmada (serviçserviço ProtheusClientePadrao), o item atual éé ser removido do serviçserviço atual para evitar duplicidade de integraçãintegração.

NotificaçãNotificação

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

Fluxo do Processo

CritéCritérios de AceitaçãAceitação

Processo	Subprocesso	DescriçãDescrição	SituaçãSituação esperada
Capturador	Captura e enfileiramento	Ao informar uma chave váválida no padrã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çãIntegração com Protheus	Ao processar um item pendente em wosk_queue, deve mapear os campos para o formato A1_*, aplicar as transformaçõtransformações definidas e registrar o resultado (sucesso ou erro) na próprópria fila, mantendo retorno e mensagem.	Fila atualizada com situaçãsituação final e detalhes para auditoria; em sucesso, cliente marcado como integrado.