ProtheusClientePadrao (STATUS: REVISANDO)

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

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

Este serviço organiza a integração de cadastros de clientes (padrão) 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 registroou mais clientes específicoficos mediante a informação dedas uma chave (ou lista de chaves) no formato A1_LOJA-A1_COD,chaves, com validação obrigatória do formato no padrão.o A1_LOJA-A1_COD. Caso algumaa chave informada esteja fora do formato esperado,padrão, o processo é imediatamente interrompido com erro de chave inválida.lida, garantindo integridade e previsibilidade no fluxo.

Permite a captura automática (via agendador de tarefas) a origem dos dados é a view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO, consultada com projeção predefinida, sendo o filtro por loja (A1_LOJA) e código (A1_COD) aplicado dinamicamente durante a execução. Para cada registro localizado, o conteúdo é encaminhado para a fila de processamento, onde será transformado e posteriormente enviado ao Protheus, mantendo o mesmo padrão de chave para identificação e rastreabilidade do registro na fila.

Fonte

A entrada é obtida por consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO. O
Consulta principal (filtro (WHERE)por é 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: Leitura:Consulta consulta nada view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAOWOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL.

para

Validação obter(captura osmanual): dados do cliente a partir daexige chave informada.
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:

• A1_NOME, A1_NREDUZ: remove o caractere | e aplica remoção de acentos.
• A1_END, A1_BAIRRO, A1_BAIRRO: 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: Requisição HTTP
• Recurso: /rest/cliente
• Método HTTP: POST
• Cabeçalhos:
  • tenantId: 01,01SD0001

Exemplo de payload enviado (JSON):

{
  "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

retorno

AntesAusência dode envioresposta: aoSe Protheus,não houver retorno, o conteúdoitem doé clientefinalizado passacom pelaserro seguintese alterações:a mensagem indica falta de resposta.

Resposta

• A1_NOMEinválida/inesperada:, A1_NREDUZ: removeSe o caractereretorno | e aplica remoçãnão defor acentos.
um
• A1_END, A1_BAIRRO, A1_BAIRRO: aplica remoção de acentos.
• A1_CODPAIS: converte para inteiro e padroniza com 5 dígitos, preenchendo com zeros à esquerda (ex.: 1058 → 01058).

Integraçãoobjeto com o Protheus

campo Mensagem, o item é finalizado com erro e a mensagem indica falha na decodificação.

ChamadaFalha: 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 integração comerro, o Protheusprocesso registra o cliente como integrado e grava o retorno na fila.

• Chamada: Requisição HTTP
• Recurso: /rest/cliente
• Método HTTP: POST
• Cabeçalhos:
  • tenantId: 01,01SD0001

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.
Descrição Conceitual

Persistência e limpeza após sucesso

• Persistência: o resultado da integração (sucesso/erro), mensagem e resposta são registrados na fila de processamento.
• 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

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 registro é 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 registro como sucesso na fila.

Sucesso: quando a resposta não indica erro, o registro é 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 registro 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 fila de processamento para rastreabilidade.

Encaminhamento em cenário de erro

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

Notificação

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 registroitem correspondente na fila de processamento.	registroItem pendente registrado na fila de processamento,fila, pronto para processamento.processamento, com chave consistente.
Fila de Processamento	Transformação e envio	Ao processar um registro pendente, deve montarestruturar o payload comconforme osestrutura campos A1_* edefinida, aplicar as alteraçtransformações documentadas (remoção de |, remoção de acentosnecessárias e padronizaçãchamar o derecurso A1_CODPAIS/rest/cliente), realizandono aProtheus chamadavia dePOST integraçãcom o aocabeçalho Protheus.tenantId.	Fila atualizada com resultado:situação sucessofinal (e detalhes para auditoria; em sucesso, cliente marcado como integrado) ou erro (mensagem e resposta registradas).
Fila de Processamento	Notificação de erros	Quando existirem registros com erro, deve gerar relatório a partir da fila de processamento 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.integrado.