Ir para o conteúdo principal

LojaTributacao

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 busca o imposto e FILTRO via aplica filtro.

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 consulta de dados 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 consulta de dados 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

Visão geral do conteudo: o payload enviado para integração é composto pelo registro principal de CTB_EXCECAO_IMPOSTO (com colunas derivadas de NATUREZAS_SAIDAS e NATUREZAS_ENTRADAS) e pelos arrays IMPOSTO e FILTRO anexados no capturador.

Campos principais do objeto raiz (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.
DATA_PARA_TRANSFERENCIA datetime/string sim Data de corte usada na captura automática e no agendamento de processamento da fila.
CODIGO_FISCAL_OPERACAO, CTB_TIPO_OPERACAO, INDICADOR_CFOP, INDICADOR_FISCAL_TERCEIRO string não Metadados fiscais da exceção que direcionam regras de operação.
UF, UF_FILIAL, UF_TERCEIRO, COD_MUNICIPIO_IBGE, DESC_MUNICIPIO_TERCEIRO string não Contexto geográfico/fiscal da operação tributária.
DESC_EXCECAO, DESC_DETALHADA, NOME_CLIFOR string não Descrições textuais e identificação complementar da regra.
NATUREZA_SAIDA, NATUREZA_ENTRADA, NATUREZA_E, DESC_NATUREZA_E, DESC_NF_E string não Naturezas fiscais do registro e campos consolidados dos joins de natureza.
CLASIF_CONTABLE_E, CLASSIF_CONTABIL_E, CM_ITEM_COMPOSICAO_E, CTB_TIPO_OPERACAO_E, TIPO_OPERACAO_E string não Classificação contábil consolidada entre natureza de entrada e saída.
INATIVO, INATIVO_E, EXCLUSIVO_CADASTRO, APLICA_ENTRADA, APLICA_SAIDA, NAO_FATURA string/boolean não Indicadores de aplicação, disponibilidade e comportamento do registro.
DT_INICIO_VIGENCIA, DT_FIM_VIGENCIA date/string não Período de vigência da exceção fiscal.
TRIBUT_ICMS, TRIBUT_ORIGEM, TIPO_TRIBUTACAO, CST_IBS_CBS, DESCRICAO_CST_IBS_CBS, CCLASSTRIB, DESCRICAO_CCLASSTRIB string/number não Conjunto de enquadramentos e classificadores tributários usados pela integração.
CODIGO_ENQUADRAMENTO, CODIGO_CLASSE_TRIBUTACAO, CODIGO_ITEM, MATRIZ_FISCAL, COD_INF_ADICIONAL, USA_SUB_ITEM_APURACAO string não Referências de enquadramento e identificação de item/regra complementar.
CLASSIF_FISCAL_INI, CLASSIF_FISCAL_FIM, CODIGO_CEST_INI, CODIGO_CEST_FIM string não Faixas de classificação fiscal e CEST consideradas na exceção.
ACERTO_CONTAS, ID_INFO_PGTO, GERA_ATIVO, INTERCOMPANY_E, IRRF, LANCAMENTO_PADRAO_E, LANCAMENTO_PADRAO_IMPOSTO_E, LX_TIPO_LANCAMENTO_E, NAO_MOSTRA_VALORES_E, NATUREZA_ENTRADA_AUTOMATICA, NATUREZA_CONTABILIZAR, OBS1_E, OBS2_E, POSSUI_ICMS, RATEIO_CENTRO_CUSTO_OSK, TIPO_FATURAMENTO string/number/boolean não Atributos contábeis e operacionais derivados das tabelas de natureza.
IMPOSTO array<object> sim Lista detalhada de impostos da exceção (origem: CTB_EXCECAO_IMPOSTO_ITEM + joins).
FILTRO array<object> sim Lista de filtros aplicados à exceção (origem: CTB_EXCECAO_IMPOSTO_FILTRO).

Estrutura de cada item em IMPOSTO:

Campo Tipo Descrição
ID_EXCECAO_IMPOSTO, ID_IMPOSTO, ID_PROCESSO, ID_SUB_ITEM_APURACAO_E, ID_EXCECAO_AJUSTE, ID_IMPOSTO_AJUSTE, ID_IMPOSTO_AJUSTE_SPED string/number Identificadores principais do imposto e dos ajustes associados.
ISENTO_OU_OUTROS, PORCENT_REDUCAO_DE_BASE, TAXA_IMPOSTO, PORC_RECUPERACAO, LIMITE_MINIMO_BASE, VALOR_MIN_ARRECADACAO_E, VALOR_MAX_ARRECADACAO_E, ALIQUOTA, ALIQUOTA_FIXA number/string Valores e parâmetros numéricos para cálculo e limitação do imposto.
TEXTO_LEGAL, CODIGO_ARRECADACAO, CODIGO_HISTORICO, SITUACAO_TRIBUTARIA, SITUACAO_TRIBUTARIA_MUNICIPAL, COD_CONTRIBUICAO_SOCIAL_APURADA, TIPO_CREDITO, NATUREZA_RECEITA, COD_BC_CREDITO, SUB_ITEM_SPED, COD_INF_ADICIONAL, NUMERO_PROCESSO, NUMERO_PROCESSO_E, CST, COD_BENEFICIO_FISCAL, CODIGO_AJUSTE, CODIGO_AJUSTE_SPED, CBENEFRBC, COD_GCRED_PRESUMIDO string Códigos legais, tributários e de escrituração fiscal (SPED e correlatos).
AGREGA_APOS_DESCONTO_E, INCIDENCIA_E, AGREGA_APOS_ENCARGO_E, VALIDA_VALOR_PARCELA_E, ZERA_VALOR_CONTABIL, ZERA_TAXA_IMPOSTO, ZERA_BASE_IMPOSTO, ZERA_VALOR_IMPOSTO, ZERA_VALOR_EXCLUIDO, EXCLUI_ICMS_PIS_COFINS, NAO_SOMA_APURACAO, DESCONTA_IMPOSTO_PRIMEIRA_PARC, DESCONTAR_VALOR_IMPOSTO_FATURA, DESCONTO_SIMPL_MENSAL, UTL_IMP_ESPELHO, GERA_NA_ENTRADA, GERA_NA_SAIDA, GERA_NA_LOJA, INATIVO, INDICA_UF_APURACAO, GERAR_C197_SPED, GERAR_E111_SPED, GERAR_E113_SPED, GERAR_E115_SPED, GERAR_C597_SPED, GERAR_D197_SPED, GERAR_E220_SPED, GERAR_E311_SPED, GERAR_1921_SPED, GERAR_C857_SPED, GERAR_C897_SPED, GERAR_E112_SPED, GERAR_E230_SPED, AJ_DEC_DOCUMENTO_FISCAL, ICMS_ANTECIPADO, GERAR_BENEF_RBC, GERAR_GCRED_PRESUMIDO, GERAR_E240_SPED, CREDITO_PRESUMIDO string/boolean Flags de cálculo, agregação, exclusão e geração de registros fiscais.
IMPOSTO, NOME_TECNICO, OBS_IMPOSTO, ID_IMPOSTO_APURAR, TIPO_APURACAO, TIPO_CALCULO_APURACAO, ID_IMPOSTO_SOMA_APURACAO, ID_IMPOSTO_UX, TABELA, CAMPO_07_08, LX_CODIGO_APURACAO, UF_E, COLUNA_IMP_AGREGADO, EXCECAO_CLASSIF_FISCAL, INDICA_REC_ALIQUOTA_BASE, INDICADOR_INCENTIVO, USA_TAB_PRECO_BASE, RED_ALIQUOTA_CBS_IBS, CRIADO_USUARIO, CALCULO_DECIMAL, NRO_CASAS_DECIMAIS string/number Metadados do imposto, configurações de apuração e ajustes de integração.

Estrutura de cada item em FILTRO:

Campo Tipo Descrição
ID_EXCECAO_IMPOSTO, ID_FILTRO, TABELA_COLUNA, TIPO_COLUNA, TAMANHO_COLUNA, FILTRO_COLUNA, DESC_VALOR string/number Metadados do filtro associado à exceção.
VALOR string ou array<object> Valor do filtro; quando TABELA_COLUNA é NATUREZA_ENTRADA ou NATUREZA_SAIDA, o valor é expandido para uma lista de objetos com os campos de natureza consolidados (ex.: NATUREZA_E, DESC_NATUREZA_E, TIPO_OPERACAO_E).

Exemplo de payload enviado para o endpoint (JSON):

{
  "key": "<OPCIONAL>",
  "ID_EXCECAO_IMPOSTO": "<ID>",
  "CODIGO_FISCAL_OPERACAO": "<CODIGO>",
  "CTB_TIPO_OPERACAO": "<TIPO>",
  "UF": "<UF>",
  "DESC_EXCECAO": "<TEXTO>",
  "NATUREZA_ENTRADA": "<COD_NAT_ENTRADA>",
  "NATUREZA_SAIDA": "<COD_NAT_SAIDA>",
  "DATA_PARA_TRANSFERENCIA": "<DATA_HORA>",
  "IMPOSTO": [
    {
      "ID_IMPOSTO": "<ID_IMPOSTO>",
      "TAXA_IMPOSTO": "<TAXA>",
      "SITUACAO_TRIBUTARIA": "<SITUACAO>",
      "IMPOSTO": "<DESCRICAO_IMPOSTO>"
    }
  ],
  "FILTRO": [
    {
      "ID_FILTRO": "<ID_FILTRO>",
      "TABELA_COLUNA": "NATUREZA_SAIDA",
      "VALOR": [
        {
          "NATUREZA_E": "<COD_NATUREZA>",
          "DESC_NATUREZA_E": "<DESCRICAO>",
          "TIPO_OPERACAO_E": "<TIPO_OPERACAO>"
        }
      ]
    }
  ]
}
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/atualiza tributação
  • 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

wosk_loja_tributacao.jpg


Critérios de Aceitação
Processo Subprocesso Descrição Situação esperada
Fila de Processamento Integração Deve enviar o payload completo ao atualiza tributação e persistir retorno na tabela da fila de integração. Situação coerente com o JSON retornado.
Nenhum comentário
Voltar ao topo