LojaTabelaCruzada (STATUS: DOCUMENTADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Tabela Cruzada ICMS)
Biblioteca	wosk_loja_tabela_cruzada
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 Tabela Cruzada (LINX → ILLI).

Descrição

Este serviço de tabela cruzada de ICMS envia combinações UF x UF destino com alíquotas de saída e entrada para o ILLI.
A captura parte de UNIDADES_FEDERACAO_ICMS com chave composta UF-UF_DESTINO.

Capturador

Descrição Conceitual

A captura automática consulta UNIDADES_FEDERACAO_ICMS quando o serviço LojaTabelaCruzada está apto, com data mínima padrão quando o filtro está vazio, ordenação por DATA_PARA_TRANSFERENCIA e paginação conforme o limite configurado para o serviço LojaTabelaCruzada.

A captura por chave usa o par UF e UF_DESTINO extraídos da chave.

Fonte

Origem consultada: tabela UNIDADES_FEDERACAO_ICMS.

Consulta principal:

SELECT
    UF,
    UF_DESTINO,
    ICMS_SAIDA,
    ICMS_ENTRADA,
    DATA_PARA_TRANSFERENCIA,
    INATIVO,
    LX_STATUS_REGISTRO,
    CODIGO_TABELA_ICMS_PARTILHA
FROM
    UNIDADES_FEDERACAO_ICMS

Operações com Dados

Leitura: conforme Fonte.

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

Consulta dinâmica (captura por chave): WHERE UF = ... AND UF_DESTINO = ....

Persistência: grava na Fila de Processamento com serviço LojaTabelaCruzada e chave UF-UF_DESTINO.

Fila de Processamento

Descrição Conceitual

Normaliza ICMS_SAIDA e ICMS_ENTRADA com setNumeric antes do envio. Em seguida chama o ILLI e persiste retorno e situação na tabela da fila de integração.

Estruturação de Dados

Campos do `conteudo`
Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Chave de API quando exigida pela plataforma.
`UF`	string	sim	UF origem.
`UF_DESTINO`	string	sim	UF destino.
`ICMS_SAIDA`	number	sim	Alíquota de saída (normalizada no envio).
`ICMS_ENTRADA`	number	sim	Alíquota de entrada (normalizada no envio).
`DATA_PARA_TRANSFERENCIA`	string	sim	Data de transferência.

Exemplo de payload enviado para o endpoint (JSON):

{
  "UF": "SP",
  "UF_DESTINO": "RJ",
  "ICMS_SAIDA": 12,
  "ICMS_ENTRADA": 12,
  "DATA_PARA_TRANSFERENCIA": "<DATA_HORA>"
}

Tratamento de Dados

ICMS_SAIDA, ICMS_ENTRADA: normalizados com setNumeric antes da chamada ao ILLI.

Integração com o ILLI

Chamada: Requisição HTTP

Recurso: /bibliotecas/0b2c5127-7e14-4f17-a4bb-1cdc30a741a8/ilx_tributacao/api/setTabelaCruzada

Método HTTP: POST

Corpo: objeto JSON igual ao conteudo após normalização numérica.

Tratamento de retorno

Padrão success/message; situação 2 ou 4 na tabela da fila de integração.

Notificação

A notificação de erros consulta registros com falha na tabela da fila de integração para o serviço LojaTabelaCruzada 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	Envio ILLI	Deve normalizar alíquotas, chamar `setTabelaCruzada` e persistir situação na tabela da fila de integração.	Retorno interpretado corretamente.