ProtheusCliente (STATUS: REVISADO)

Documentação Técnica

Histórico de Versões

Descrição

Este serviço 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, a partir do campo DATA_PARA_TRANSFERENCIA. 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 registro na fila de processamento 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.

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 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: Requisição HTTP
• Recurso: /rest/cliente
• Método: POST
• Cabeçalhos:
  • tenantId: 01,01SD0001

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

Em erro no retorno do Protheus, 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 registro alternativo na fila de processamento; Se for capturado, ou já existir, remove o registro atual para evitar duplicidade.

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.
link: Cliente Integrado

Notificação

Fluxo do Processo

Critérios de Aceitação