Ir para o conteúdo principal

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. 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
  • 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 erro. Quando success não está vazio, situação sucesso; caso contrário situação erro.

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

Diagrama 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.
Nenhum comentário
Voltar ao topo