LojaCfopCaracteristica (STATUS: DOCUMENTADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (CFOP Característica)
Biblioteca	wosk_loja_cfop_caracteristica
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 CFOP Característica (LINX → ILLI).

Descrição

Este serviço de tributação envia ao ILLI as características de CFOP cadastradas no LINX a partir da tabela de relacionamento fiscal.
Garante captura por data, fila e integração com retorno tratado.

Capturador

Descrição Conceitual

A captura automática consulta CTB_LX_CARACTERISTICA_CFOP quando o serviço LojaCfopCaracteristica está apto, com DATA_PARA_TRANSFERENCIA mínima, ordenação ascendente e paginação conforme o limite configurado para o serviço LojaCfopCaracteristica, alinhada ao processamento cronológico e ao semáforo. A chave de fila é CTB_TIPO_OPERACAO-INDICADOR_CFOP-INDICADOR_FISCAL_TERCEIRO.

A captura por chave aceita três partes separadas por hífen; relê o registro e reenfileira preservando token quando existir.

Fonte

Origem consultada: tabela CTB_LX_CARACTERISTICA_CFOP.

Consulta principal:

SELECT
    CODIGO_FISCAL_EXTERIOR,
    CODIGO_FISCAL_INTERESTADUAL,
    CODIGO_FISCAL_OPERACAO,
    CTB_TIPO_OPERACAO,
    INDICADOR_CFOP,
    INDICADOR_FISCAL_TERCEIRO,
    INATIVO,
    DATA_PARA_TRANSFERENCIA
FROM
    CTB_LX_CARACTERISTICA_CFOP

Operações com Dados

Leitura: conforme Fonte.

Consulta dinâmica (captura automática): WHERE DATA_PARA_TRANSFERENCIA >= filtro, ORDER BY DATA_PARA_TRANSFERENCIA ASC, OFFSET ... FETCH NEXT ... conforme limite do serviço LojaCfopCaracteristica.

Consulta dinâmica (captura por chave): WHERE CTB_TIPO_OPERACAO = ... AND INDICADOR_CFOP = ... AND INDICADOR_FISCAL_TERCEIRO = ....

Validação (captura por chave): três partes na chave; senão erro de chave inválida.

Persistência: serviço LojaCfopCaracteristica, chave composta pelos três indicadores.

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 ILLI.
O envio usa ilx_tributacao/api/setCfopCaracteristica na biblioteca de destino do código.

Estruturação de Dados

Campos do `conteudo`
Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Chave de API quando exigida pela plataforma de bibliotecas.
`CODIGO_FISCAL_EXTERIOR`	string	sim	Origem consultada: coluna `CODIGO_FISCAL_EXTERIOR` em `CTB_LX_CARACTERISTICA_CFOP`.
`CODIGO_FISCAL_INTERESTADUAL`	string	sim	Origem consultada: coluna `CODIGO_FISCAL_INTERESTADUAL` em `CTB_LX_CARACTERISTICA_CFOP`.
`CODIGO_FISCAL_OPERACAO`	string	sim	Origem consultada: coluna `CODIGO_FISCAL_OPERACAO` em `CTB_LX_CARACTERISTICA_CFOP`.
`CTB_TIPO_OPERACAO`	string	sim	Origem consultada: coluna `CTB_TIPO_OPERACAO` em `CTB_LX_CARACTERISTICA_CFOP`.
`INDICADOR_CFOP`	string	sim	Origem consultada: coluna `INDICADOR_CFOP` em `CTB_LX_CARACTERISTICA_CFOP`.
`INDICADOR_FISCAL_TERCEIRO`	string	sim	Origem consultada: coluna `INDICADOR_FISCAL_TERCEIRO` em `CTB_LX_CARACTERISTICA_CFOP`.
`INATIVO`	string	sim	Origem consultada: coluna `INATIVO` em `CTB_LX_CARACTERISTICA_CFOP`.
`DATA_PARA_TRANSFERENCIA`	string	sim	Origem consultada: coluna `DATA_PARA_TRANSFERENCIA` em `CTB_LX_CARACTERISTICA_CFOP`.

Exemplo ilustrativo de corpo enviado ao ILLI (estrutura alinhada ao conteudo):

{
  "key": "<API_KEY_SE_APLICAVEL>",
  "CODIGO_FISCAL_EXTERIOR": "<CODIGO_FISCAL_EXTERIOR>",
  "CODIGO_FISCAL_INTERESTADUAL": "<CODIGO_FISCAL_INTERESTADUAL>",
  "CODIGO_FISCAL_OPERACAO": "<CODIGO_FISCAL_OPERACAO>",
  "CTB_TIPO_OPERACAO": "<CTB_TIPO_OPERACAO>",
  "INDICADOR_CFOP": "<INDICADOR_CFOP>",
  "INDICADOR_FISCAL_TERCEIRO": "<INDICADOR_FISCAL_TERCEIRO>",
  "INATIVO": "<INATIVO>",
  "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA>"
}

Tratamento de Dados

Base do envio: o conteudo é enviado ao ILLI sem mapeamento adicional no arquivo analisado.

Montagem da chave: na captura automática, a chave concatena CTB_TIPO_OPERACAO, INDICADOR_CFOP e INDICADOR_FISCAL_TERCEIRO do registro atual.

Integração com o ILLI

Chamada: Requisição HTTP

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

Método HTTP: POST

Cabeçalhos: os definidos internamente pela rotina de integração ILLI (não fixados neste arquivo).

Corpo: conteudo do registro na fila.

Tratamento de retorno

Ausência de resposta ou retorno sem success e sem message gera exceção e situação 4. Quando success não está vazio, situação 2; caso contrário situação 4.

Notificação

A notificação de erros consulta registros com falha na tabela da fila de integração para o serviço LojaCfopCaracteristica 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
Capturador	Captura automática	Deve paginar `CTB_LX_CARACTERISTICA_CFOP` por data e gravar na fila com chave tripla.	Registros pendentes na fila de integração.
Capturador	Captura por chave	Deve validar três partes e reenfileirar com token quando existir.	Chave inválida gera exceção.
Fila de Processamento	Integração ILLI	Deve enviar ao recurso `/bibliotecas/0b2c5127-7e14-4f17-a4bb-1cdc30a741a8/ilx_tributacao/api/setCfopCaracteristica`, interpretar sucesso ou erro com mensagem e persistir situação na tabela da fila de integração.	Situação final alinhada ao retorno do ILLI.