ProtheusCliente (STATUS: AVALIANDO-GUS)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza a integração de cadastros de clientes do LINX para o Protheus, mantendo rastreabilidade do processamento e do retorno da integração.

Capturador

Descrição Conceitual

O capturador recupera clientes a partir da fonte WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES e também permite captura manual por chave, garantindo validação do formato e previsibilidade do fluxo. No processo incremental, os registros são filtrados e ordenados por DATA_PARA_TRANSFERENCIA e paginados, permitindo continuidade pela posição registrada.

Esse fluxo caracteriza processamento cronológico (ordenação/paginação por data). Conceito cronológico.

Fonte

Consulta principal (filtro por data e paginação):

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
WHERE 
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY 
    DATA_PARA_TRANSFERENCIA ASC
OFFSET <OFFSET> ROWS FETCH NEXT <LIMITE> ROWS ONLY

Consulta de captura manual (WHERE construído dinamicamente a partir da chave):

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
WHERE 
    A1_LOJA = '<A1_LOJA>'
    AND A1_COD = '<A1_COD>'
    AND CGC_CPF = '<CGC_CPF (opcional)>'

Operações com Dados

Entrada de dados: registros vindos de WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES.

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

Persistência (fila): para cada registro capturado é gravado um item na tabela wosk_queue para processamento posterior, usando o serviço ProtheusCliente e chave no padrão A1_LOJA-A1_COD-CGC_CPF.

Persistência (continuidade): a posição do capturador (índices como offset, chave_posicao, data_posicao, filtro, situacao) é atualizada ao longo do fluxo para permitir retomada controlada (tabela interna não explicitada neste arquivo).

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

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

Transformações aplicadas no payload antes do envio ao Protheus (campos e regra):

- A1_NOME, A1_NREDUZ: remove o caractere | e remove acentuação.
- A1_END, A1_BAIRRO, A1_CONTATO: remove acentuação.
- A1_CODPAIS: converte para numérico e preenche à esquerda com 0 até 5 dígitos.

Integração com o Protheus

Chamada de integração com o Protheus

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

Exemplo de payload enviado: ver seção Estruturação de Dados (JSON completo conforme $field).

Tratamento de retorno

Classificação do retorno do Protheus (impacta diretamente a situação do item na tabela wosk_queue):

- Ausência de resposta: finaliza como erro (situacao = 4) e registra a mensagem.
- Resposta inválida/inesperada: se não for um array ou não trouxer Mensagem, finaliza como erro (situacao = 4).
- Indicadores de erro: se existir code no retorno ou se Mensagem for ERRO, finaliza como erro (situacao = 4).
- Condição de sucesso: quando não houver indicador de erro, finaliza como sucesso (situacao = 2) e marca o cliente como integrado.

Rotinas Inteligentes
setProtheusClienteIntegrado: após confirmação de sucesso da integração. Marca o cliente (A1_LOJA-A1_COD) como integrado no controle de integração.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/setprotheusclienteintegrado

Encaminhamento em cenário de erro

Em erro no retorno do Protheus (situacao = 4), o fluxo aciona uma captura alternativa do cliente pelo serviço ProtheusClientePadrao para a chave A1_LOJA-A1_COD e valida a existência do item alternativo na tabela wosk_queue; quando existir, o item do fluxo original pode ser removido para evitar duplicidade.

Notificação

Fluxo do Processo

Critérios de Aceitação