LojaTributacao (STATUS: DOCUMENTADO)

Documentação Técnica

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

Descrição

Este serviço de exceções fiscais sincroniza registros de CTB_EXCECAO_IMPOSTO enriquecidos com naturezas de entrada e saída e listas de impostos e filtros calculados no monitor.
Cada registro é enviado ao ILLI com chave ID_EXCECAO_IMPOSTO.

Capturador

Descrição Conceitual

A captura automática consulta a projeção principal (exceção com joins em NATUREZAS_SAIDAS e NATUREZAS_ENTRADAS) quando o serviço LojaTributacao está apto, com DATA_PARA_TRANSFERENCIA mínima e paginação conforme o limite configurado para o serviço LojaTributacao. Antes de enfileirar, anexa IMPOSTO via getImposto e FILTRO via getFiltro.

A captura por chave reprocessa pelo ID_EXCECAO_IMPOSTO.

Fonte

Origem consultada: CTB_EXCECAO_IMPOSTO com LEFT JOIN em NATUREZAS_SAIDAS e NATUREZAS_ENTRADAS conforme a viewQuery completa no arquivo-fonte (dezenas de colunas fiscais e contábeis).

Consulta principal:

SELECT
    EI.CODIGO_FISCAL_OPERACAO,
    EI.ID_EXCECAO_IMPOSTO,
    EI.UF,
    EI.DESC_EXCECAO,
    EI.NATUREZA_SAIDA,
    EI.NATUREZA_ENTRADA,
    EI.DATA_PARA_TRANSFERENCIA,
    <demais colunas EI, NS, NE conforme viewQuery do arquivo>
FROM
    CTB_EXCECAO_IMPOSTO EI (NOLOCK)
    LEFT JOIN NATUREZAS_SAIDAS NS (NOLOCK) ON (NS.NATUREZA_SAIDA = EI.NATUREZA_SAIDA)
    LEFT JOIN NATUREZAS_ENTRADAS NE (NOLOCK) ON (NE.NATUREZA = EI.NATUREZA_ENTRADA)

Operações com Dados

Leitura: conforme Fonte mais anexos IMPOSTO e FILTRO.

Consulta dinâmica (captura automática): WHERE EI.DATA_PARA_TRANSFERENCIA >= filtro, ordenação e paginação conforme limite do serviço LojaTributacao.

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

Fila de Processamento

Descrição Conceitual

O conteudo completo (incluindo IMPOSTO e FILTRO) é enviado ao ILLI sem transformação adicional no processamento da fila.

Estruturação de Dados

Campos de referência do `conteudo`
Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Chave de API quando exigida pela plataforma.
`ID_EXCECAO_IMPOSTO`	string	sim	Identificador da exceção; chave na fila.
Mais colunas da exceção e joins; objetos `IMPOSTO` e `FILTRO` anexados no capturador.

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

{
  "ID_EXCECAO_IMPOSTO": "<ID>",
  "DESC_EXCECAO": "<TEXTO>",
  "IMPOSTO": [],
  "FILTRO": [],
  "DATA_PARA_TRANSFERENCIA": "<DATA_HORA>"
}

Tratamento de Dados

Montagem de IMPOSTO e FILTRO no capturador; fila repassa o objeto integralmente.

Integração com o ILLI

Chamada: Requisição HTTP
Recurso: /bibliotecas/0b2c5127-7e14-4f17-a4bb-1cdc30a741a8/ilx_tributacao/api/setTributacao
Método HTTP: POST
Corpo: conteudo do registro na fila.

Tratamento de retorno

Padrão success/message; situação sucesso ou 4.

Notificação

A notificação de erros consulta registros com falha na tabela da fila de integração para o serviço LojaTributacao 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	Deve enviar o payload completo ao `setTributacao` e persistir retorno na tabela da fila de integração.	Situação coerente com o JSON retornado.