LojaProduto (STATUS: DOCUMENTADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Produto Loja)
Biblioteca	wosk_loja_produto
Data	26/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
26/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo Loja Produto (LINX → ILLI).

Descrição

Este serviço de cadastro de produto no LINX monta um payload rico com grade, preços e metadados e envia ao ILLI em uma única chamada de produto.
O capturador lê a tabela de produtos com joins (coleção, CEST, etc.), complementa com SKU via PRODUTOS_BARRA e listas de preços, e enfileira pela chave PRODUTO.

Capturador

Descrição Conceitual

A captura automática consulta a projeção principal em PRODUTOS com joins quando o serviço LojaProduto está apto, com filtro em DATA_PARA_TRANSFERENCIA, ordenação por data e produto e paginação conforme o limite configurado para o serviço LojaProduto. Antes de enfileirar, anexa SKU (grades) e PRECOS via métodos auxiliares.

A captura por código reprocessa um PRODUTO específico com a mesma projeção e enriquecimento.

Fonte

Origem consultada: tabela PRODUTOS com joins a cadastros auxiliares (coleção, CEST e demais colunas da viewQuery no arquivo-fonte).

Consulta principal:

SELECT
    P.PRODUTO,
    P.TIPO_PRODUTO,
    P.DESC_PRODUTO,
    P.GRUPO_PRODUTO,
    P.SUBGRUPO_PRODUTO,
    P.LINHA,
    P.GRIFFE,
    P.UNIDADE,
    P.FABRICANTE,
    P.REFER_FABRICANTE,
    P.TRIBUT_ICMS,
    P.TRIBUT_ORIGEM,
    P.DATA_CADASTRAMENTO,
    P.SUJEITO_SUBSTITUICAO_TRIBUTARIA,
    P.OBS,
    P.SEXO_TIPO,
    P.CLASSIF_FISCAL,
    P.STATUS_PRODUTO,
    P.DATA_PARA_TRANSFERENCIA,
    TLC.CODIGO_CEST,
    CL.COLECAO,
    CL.DESC_COLECAO,
    <demais colunas de coleção conforme arquivo>
FROM
    PRODUTOS P (NOLOCK)
    <JOINs conforme viewQuery do arquivo-fonte>

Operações com Dados

Leitura: conforme Fonte; enriquecimento com getProdutoBarra (PRODUTOS_BARRA) e getPrecos (preços por cor/tabela).

Consulta dinâmica (captura automática): WHERE P.DATA_PARA_TRANSFERENCIA >= filtro, ORDER BY P.DATA_PARA_TRANSFERENCIA ASC, P.PRODUTO ASC, paginação conforme limite do serviço LojaProduto.

Persistência: grava na Fila de Processamento com serviço LojaProduto e chave PRODUTO.

Fila de Processamento

Descrição Conceitual

O processamento monta produto_grade a partir de SKU, precos a partir de PRECOS e tributação quando TRIBUT_ICMS está informado; converte SEXO_TIPO numérico para texto (MASCULINO, FEMININO, UNISSEX, INFANTIL ou INDEFINIDO); exige PRECOS, SKU e SEXO_TIPO. O objeto arr inclui identificação, descrições, grupo de produto, coleção opcional, PCP opcional, marca, situação derivada de STATUS_PRODUTO, grades, preços e datas. Mensagens de ausência de preço ou grade podem ser tratadas como ignoradas com sucesso em condições específicas.

Estruturação de Dados

Raiz do objeto enviado ao ILLI (campos principais)
Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Não aplicado no objeto raiz gerado no código analisado.
`id`	boolean	sim	Fixo `false` no fluxo.
`tipo`	string	sim	Texto fixo de tipo de grade.
`codigo`	string	sim	`PRODUTO`.
`nome`	string	sim	`DESC_PRODUTO`.
`produto_grade`	array	sim	Variações por cor/tamanho (ver tabela abaixo).
`precos`	array	sim	Itens de preço por cor/tabela/tamanho.
`grupo_produto`	array	sim	Grupo, subgrupo, tipo e sexo textual.

Estrutura de cada elemento de `produto_grade` (resumo)
Campo	Tipo	Descrição
`codigo`	string	Código de barras calculado ou informado.
`codigo_ean`	string	EAN quando diverge do código concatenado.
`cor`	object	`codigo` e `nome` da cor.
`tamanho`	object	`codigo` e `nome` da grade.
`grupo_tributacao`	object	`origem` e `cst` quando aplicável.

Exemplo de payload enviado para o endpoint (JSON) — estrutura resumida:

{
  "id": false,
  "tipo": "Grade Simples",
  "codigo": "<PRODUTO>",
  "nome": "<DESC_PRODUTO>",
  "produto_grade": [],
  "precos": [],
  "grupo_produto": ["<GRUPO>", "<SUBGRUPO>", "<TIPO>", "<SEXO_TEXTO>"],
  "data": "<DATA_PARA_TRANSFERENCIA>"
}

Tratamento de Dados

Ver lista na descrição da fila: arredondamento de preços, montagem de grades, validações de preço/grade/sexo e tratamento de exceções com prefixo "Ignorado" quando aplicável.

Integração com o ILLI

Chamada: Requisição HTTP
Recurso: /bibliotecas/9750fbda-368f-4f63-87f9-667356bc040b/ilx_produto/api/setProduto
Método HTTP: POST
Corpo: objeto arr montado no processamento da fila.

Tratamento de retorno

Padrão de sucesso/erro com success e message; situação sucesso ou 4 na tabela da fila de integração; exceções com JSON não reconhecido estruturadas com error e data quando aplicável.

Notificação

A notificação de erros consulta registros com falha na tabela da fila de integração para o serviço LojaProduto e situação de erro, ordenando pelo horário de processamento para priorizar ocorrências mais antigas.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Fila de Processamento	Integração ILLI	Deve montar o payload completo e chamar `setProduto`, interpretar sucesso ou erro com mensagem e persistir situação na tabela da fila de integração.	Situação e mensagem coerentes com o retorno.