ProtheusCliente (STATUS: PARCIAL)

Documentação Técnica

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

Histórico de Versões

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

Descrição

Esta biblioteca integra o cadastro de clientes (padrão) do LINX ao Protheus, preparando os dados e registrando o resultado do envio para acompanhamento.

Capturador

Descrição Conceitual

O capturador recebe uma chave (ou lista de chaves) no formato A1_LOJA-A1_COD, consulta a fonte de dados e localiza os registros correspondentes na view de integração.

Para cada registro encontrado, o conteúdo é encaminhado para a fila de processamento, onde será transformado e enviado ao Protheus.

Fonte

A entrada é obtida por consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO. O filtro (WHERE) é montado dinamicamente a partir da chave informada (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_PADRAO
WHERE
    A1_LOJA = '<A1_LOJA>'
    AND A1_COD = '<A1_COD>'

 

Operações com Dados

- Leitura: consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO para obter os dados do cliente a partir da chave informada.
- Persistência: os registros capturados são registrados para processamento assíncrono na tabela wosk_queue (base de integração), permitindo rastreabilidade do processamento e do resultado (sucesso/erro).

Fila de Processamento

Descrição Conceitual

A fila recebe um item pendente e utiliza o conteúdo do cliente como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização e realiza a chamada ao Protheus.

Ao final, o resultado é persistido na própria tabela wosk_queue, registrando situação, mensagem e resposta para auditoria e reprocessamento quando aplicável.

Estruturação de Dados

Mapa de campos do payload

Exemplo de payload enviado

{
  "A1_COD": "000001",
  "A1_LOJA": "01",
  "A1_CGC": "00000000000000",
  "A1_NOME": "NOME DO CLIENTE",
  "A1_PESSOA": "F",
  "A1_NREDUZ": "NOME REDUZIDO",
  "A1_END": "RUA EXEMPLO 123",
  "A1_BAIRRO": "CENTRO",
  "A1_COMPLEM": "APTO 101",
  "A1_TIPO": "N",
  "A1_EST": "SP",
  "A1_COD_MUN": "3550308",
  "A1_CEP": "01000000",
  "A1_DDI": "55",
  "A1_DDD": "11",
  "A1_TEL": "999999999",
  "A1_CONTATO": "CONTATO",
  "A1_PFISICA": "1",
  "A1_INSCR": "",
  "A1_INSCRM": "",
  "A1_DTNASC": "1980-01-01",
  "A1_EMAIL": "cliente@exemplo.com",
  "A1_PAIS": "1058",
  "A1_CODPAIS": "01058",
  "A1_CONTA": "",
  "A1_CONTRIB": "",
  "A1_TPESSOA": "",
  "A1_SUFRAMA": "",
  "A1_CALCSUF": "",
  "A1_CODMUN": "",
  "A1_MSBLQL": "N"
}

Tratamento de Dados

Antes do envio ao Protheus, o conteúdo do cliente passa pelas seguintes alterações:

• A1_NOME: remove o caractere | e aplica remoção de acentos.
• A1_NREDUZ: remove o caractere | e aplica remoção de acentos.
• A1_END: aplica remoção de acentos.
• A1_BAIRRO: aplica remoção de acentos.
• A1_CONTATO: aplica remoção de acentos.
• A1_CODPAIS: converte para inteiro e padroniza com 5 dígitos, preenchendo com zeros à esquerda (ex.: 1058 → 01058).

Integração com o Protheus

Chamada de integração com o Protheus

• Recurso: cliente
• Método HTTP: POST
• Cabeçalhos:
  • tenantId: 01,01SD0001

Tratamento de retorno (obrigatório)

• Ausência de resposta: registra erro com a mensagem JSON: NÃO HOUVE RESPOSTA.
• Resposta inválida/inesperada: quando não é array ou não possui Mensagem, registra erro com a mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
• Indicadores de erro: quando Mensagem é ERRO (ou quando há presença de code), o item é marcado como erro na fila e a resposta é armazenada para auditoria.
• Condição de sucesso: quando não há indicador de erro, a rotina marca o cliente como integrado e conclui o item como sucesso na fila.

Rotinas Inteligentes

Foi identificada a chamada da rotina inteligente setProtheusClienteIntegrado, utilizada para registrar o cliente como integrado após o retorno de sucesso do Protheus.

Persistência e limpeza após sucesso

• Persistência: o resultado da integração (sucesso/erro), mensagem e resposta são registrados na tabela wosk_queue.
• Limpeza: em caso de sucesso, a rotina remove registros auxiliares relacionados ao processo em tabelas/estruturas de controle do integrador (ex.: entidades ProtheusCliente e ProtheusClienteFull), evitando acúmulo de referências.

 

Tratamento de retorno

- Sucesso: quando a resposta não indica erro, o item é concluído como sucesso na fila e o cliente é marcado como integrado.
- Erro: quando ocorre exceção, retorno ausente/invalidado ou resposta com erro, o item permanece registrado com erro e a mensagem detalhada é armazenada para consulta.
- Auditoria: o tempo de processamento e os detalhes da requisição/resposta são persistidos na tabela wosk_queue para rastreabilidade.

Encaminhamento em cenário de erro

Quando há erro no envio ou na validação da resposta, o item é mantido na tabela wosk_queue com situação de erro e mensagem correspondente, permitindo reprocessamento conforme as rotinas padrões de fila do integrador.

Notificação

SELECT
    `token`,
    `acao`,
    `chave`,
    `data_adicionado`,
    `data`,
    `mensagem` AS 'ERRO'
FROM
    `<bancoIntegrador>`.`wosk_queue`
WHERE
    `acao` = 'ProtheusClientePadrao' AND `situacao` = 4
ORDER BY
    `data` ASC

Tratamento do relatório

Destinatários: os e-mails de destino estão definidos no código da biblioteca e recebem o relatório de erros do processo.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por chave	Ao informar uma chave válida no padrão A1_LOJA-A1_COD, deve consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO e registrar o item correspondente na fila de processamento.	Item pendente registrado na wosk_queue, pronto para processamento.
Fila de Processamento	Transformação e envio	Ao processar um item pendente, deve montar o payload com os campos A1_* e aplicar as alterações documentadas (remoção de |, remoção de acentos e padronização de A1_CODPAIS), realizando a chamada de integração ao Protheus.	Fila atualizada com resultado: sucesso (cliente marcado como integrado) ou erro (mensagem e resposta registradas).
Fila de Processamento	Notificação de erros	Quando existirem itens com erro, deve gerar relatório a partir da wosk_queue filtrando pela ação ProtheusClientePadrao e ordenando por data de processamento, enviando aos destinatários configurados.	Relatório enviado e erros apresentados com mensagem legível e datas formatadas.