ProtheusClienteFull (STATUS: PARCIAL)

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

Esta biblioteca 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

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.

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

Fila de Processamento

Descrição Conceitual

Estruturação de Dados

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

Mapeamento de campos aplicado:

Campo no Payload (Protheus)	Campo de Origem
`A1_COD`	`A1_COD`
`A1_LOJA`	`A1_LOJA`
`A1_CGC`	`CGC_CPF`
`A1_NOME`	`NOME`
`A1_PESSOA`	`PESSOA`
`A1_NREDUZ`	`NOME_REDUZ`
`A1_END`	`ENDERECO`
`A1_BAIRRO`	`BAIRRO`
`A1_COMPLEM`	`COMPLEMENTO`
`A1_TIPO`	`TIPO`
`A1_EST`	`UF`
`A1_COD_MUN`	`COD_MUNICIPIO_IBGE`
`A1_CEP`	`CEP`
`A1_DDI`	`DDI`
`A1_DDD`	`DDD`
`A1_TEL`	`TELEFONE`
`A1_CONTATO`	`CONTATO`
`A1_PFISICA`	`A1_PFISICA`
`A1_INSCR`	`A1_INSCR`
`A1_INSCRM`	`INSC_MUNICIPAL`
`A1_DTNASC`	`DATA_NASC`
`A1_EMAIL`	`EMAIL`
`A1_PAIS`	`COD_PAIS_SISCOMEX`
`A1_CODPAIS`	`COD_PAIS_BC`
`A1_CONTA`	`A1_CONTA`
`A1_CONTRIB`	`A1_CONTRIB`
`A1_TPESSOA`	`A1_TPESSOA`
`A1_SUFRAMA`	`A1_SUFRAMA`
`A1_CALCSUF`	`A1_CALCSUF`
`A1_CODMUN`	`A1_CODMUN`
`A1_MSBLQL`	`STATUS`

Tratamento de Dados

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

A1_NOME, A1_NREDUZ: remove o caractere | e remove acentuação antes do envio.
A1_END, A1_BAIRRO, A1_CONTATO: remove acentuação antes do envio.
A1_CODPAIS: converte para número e preenche com zeros à esquerda até 5 dígitos (ex.: 1 → 00001).

Integração com o Protheus

Chamada: Requisição HTTP
Endpoint: cliente
Método: POST
Cabeçalhos:
- tenantId: 01,01SD0001

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ê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 a captura for confirmada (serviço ProtheusClientePadrao), o item atual é ser removido do serviço atual para evitar duplicidade de integração.

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 item pendente em wosk_queue, deve mapear os campos para o formato `A1_*`, aplicar as transformações definidas e registrar o resultado (sucesso ou erro) na própria fila, mantendo retorno e mensagem.	Fila atualizada com situação final e detalhes para auditoria; em sucesso, cliente marcado como integrado.