Ir para o conteúdo principal

LojaCfopCaracteristica

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

wosk_loja_cfop_caracteristica.drawio.jpg

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 valida os dados 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