LojaNotaFiscal

Documentação Técnica

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

Descrição

Este serviço de nota fiscal da loja recebe dados de documento fiscal pelo endpoint, valida entradas auxiliares quando informadas, resolve filial e cadastro de loja no LINX e grava ou atualiza o conjunto de tabelas de nota fiscal e documentos correlatos.
O ramo de modelo fiscal (NF-e/NFC-e ou cupom fiscal) define qual rotina de geração de XML e persistência é executada.

Endpoint (API)

O endpoint processa o array de parâmetros da requisição: aplica validação base do serviço HTTP, validações específicas de produtos e de XML quando presentes, resolve FILIAL e dados em LOJAS_VAREJO, resolve filial de destino quando informada, exige natureza de operação e monta o XML conforme o modelo (NF_MODELO 55 ou 65 versus demais). O detalhe de campos de persistência está nas subseções abaixo.

Chamada: Requisição HTTP

Recurso: /bibliotecas/4e2f7df5-e964-49d7-a3d2-f77116188fd8/wosk_loja_nota_fiscal

Método HTTP: POST

Estruturação de Dados

Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Chave de autenticação/controle da chamada.
`eventId`	string (UUID)	não	Identificador do evento da origem.
`COD_FILIAL`	string	sim	Código da filial (padronizado para busca em `FILIAIS`).
`NF_MODELO`	number	sim	Define o ramo de processamento do documento fiscal.
`NF_CHAVE`	string	sim	Chave de acesso da nota fiscal.
`NF_SERIE`, `NF_NUMERO`	number	sim	Série e número do documento fiscal.
`SITUACAO`	string	sim	Status do documento fiscal (ex.: `AUTORIZADO`).
`XML`	string	sim	XML completo do documento fiscal autorizado.
`PRODUTOS`	array de objetos	sim	Itens da nota fiscal com dados fiscais/comerciais por item.
`NATUREZA_OPERACAO_CODIGO`	string	sim	Código da natureza da operação fiscal.
`VALOR_TOTAL`, `QTDE_TOTAL`	string/number	sim	Valor total e quantidade total do documento.
`CODIGO_CLIENTE`, `COD_CLIFOR`	string/bool	não	Identificação do cliente/fornecedor associada ao documento.
`COD_FILIAL_DESTINO`	string/bool	não	Quando informado, resolve segunda filial e cadastro em `LOJAS_VAREJO` para destino.
`DATA_EMISSAO`, `DATA_AUTORIZACAO`, `DATA_SITUACAO`, `DATA_CANCELAMENTO`	string	não	Marcos de data/hora do ciclo de vida da nota fiscal.
`PROTOCOLO_AUTORIZACAO`, `PROTOCOLO_CANCELAMENTO`	string	não	Protocolos de autorização e cancelamento da NF.
`MOTIVO_CANCELAMENTO`, `CF_NUMERO_CANCELAMENTO`, `CHAVE_CFE_CANCELAMENTO`	string	não	Campos complementares usados em cenários de cancelamento.
`UF_FILIAL`, `UF_CLIENTE`	string (2)	não	Unidades federativas da filial emissora e do cliente.
`INUTILIZADO`, `FIN_EMISSAO_NFE`, `TIPO_EMISSAO_NFE`, `INDICA_CONSUMIDOR_FINAL`, `INDICA_PRESENCA_COMPRADOR`	bool/number	não	Indicadores fiscais de emissão, finalidade e presença do comprador.
`TICKET`, `TERMINAL`, `OBS`, `RESPONSAVEL`, `LANCAMENTO_CAIXA`, `CENTRO_CUSTO`, `CO`	string	não	Metadados operacionais/comerciais recebidos no payload.
`TIPO_ORIGEM`, `RECEBIMENTO`, `CODIGO_TAB_PRECO`	number/string	não	Parâmetros auxiliares de origem e classificação comercial.

Exemplo de payload enviado para o endpoint (JSON):

{
  "CO": "",
  "OBS": "",
  "XML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc ... >...</nfeProc>",
  "key": "df9b5d7f-da04-42f1-80b2-6b6bbbc39152",
  "TICKET": "",
  "eventId": "e9b9f59a-1ecd-418b-95dd-fd47e23cba43",
  "NF_CHAVE": "33260335943604001632650650001203991787414604",
  "NF_SERIE": 65,
  "PRODUTOS": [
    {
      "NCM": "33074900",
      "CFOP": "5102",
      "ITEM": 1,
      "QTDE": 1,
      "PRECO": 397,
      "INSUMO": false,
      "UNIDADE": "UN",
      "DESCRICAO": "DIFUSOR AMAZON SENSE",
      "CODIGO_EAN": "",
      "TRIBUT_ICMS": "00",
      "CODIGO_BARRA": "74055400UN",
      "TRIBUT_ORIGEM": "0",
      "ID_EXCECAO_IMPOSTO": "16296"
    },
    {
      "NCM": "33074900",
      "CFOP": "5102",
      "ITEM": 2,
      "QTDE": 1,
      "PRECO": 397,
      "INSUMO": false,
      "UNIDADE": "UN",
      "DESCRICAO": "DIFUSOR AMAZON SENSE",
      "CODIGO_EAN": "",
      "TRIBUT_ICMS": "00",
      "CODIGO_BARRA": "74055400UN",
      "TRIBUT_ORIGEM": "0",
      "ID_EXCECAO_IMPOSTO": "16296"
    }
  ],
  "SITUACAO": "AUTORIZADO",
  "TERMINAL": "",
  "NF_MODELO": 65,
  "NF_NUMERO": 120399,
  "UF_FILIAL": "RJ",
  "COD_CLIFOR": false,
  "COD_FILIAL": "000025",
  "QTDE_TOTAL": 2,
  "UF_CLIENTE": "RJ",
  "INUTILIZADO": false,
  "RECEBIMENTO": "0",
  "RESPONSAVEL": "",
  "TIPO_ORIGEM": 1,
  "VALOR_TOTAL": "627.54",
  "CENTRO_CUSTO": "",
  "DATA_EMISSAO": "2026-03-30 14:49:42",
  "DATA_SITUACAO": "2026-03-30 14:49:43",
  "CODIGO_CLIENTE": "75208520168",
  "FIN_EMISSAO_NFE": 1,
  "CODIGO_TAB_PRECO": "00",
  "DATA_AUTORIZACAO": "2026-03-30 14:49:42",
  "LANCAMENTO_CAIXA": "",
  "TIPO_EMISSAO_NFE": 1,
  "DATA_CANCELAMENTO": "",
  "COD_FILIAL_DESTINO": false,
  "MOTIVO_CANCELAMENTO": "",
  "PROTOCOLO_AUTORIZACAO": "233260750338332",
  "CF_NUMERO_CANCELAMENTO": "",
  "CHAVE_CFE_CANCELAMENTO": "",
  "PROTOCOLO_CANCELAMENTO": "",
  "INDICA_CONSUMIDOR_FINAL": 1,
  "NATUREZA_OPERACAO_CODIGO": "5102.",
  "INDICA_PRESENCA_COMPRADOR": 1
}

Operações com Dados

Validação: validação base do serviço; quando informado, validação específica de PRODUTOS e de XML.

Filial emissora: consulta em FILIAIS pelo COD_FILIAL recebido; com registro encontrado, preenchem-se FILIAL, CGC_CPF e, se COD_CLIFOR vier vazio, COD_CLIFOR a partir do cadastro da filial.

Loja: consulta em LOJAS_VAREJO por FILIAL; preenchem-se CODIGO_FILIAL e GERENTE_LOJA (código do gerente).

Filial de destino: quando COD_FILIAL_DESTINO está informado, nova consulta em FILIAIS e em LOJAS_VAREJO para obter FILIAL_DESTINO, CODIGO_FILIAL_DESTINO e, se aplicável, COD_CLIFOR_DESTINO.

Natureza de operação: exige NATUREZA_OPERACAO_CODIGO preenchido.

Ramo fiscal: para NF_MODELO 55 ou 65 executa-se a rotina de nota fiscal; nos demais modelos executa-se a rotina de cupom fiscal; o retorno atualiza o array de resposta (incluindo XML conforme o ramo).

Persistência: insert/update e detalhamento por item e impostos ocorrem dentro das rotinas chamadas (tabelas como LOJA_NOTA_FISCAL, itens e impostos, ou estruturas de cupom conforme o modelo).

Tratamento de Dados

Chave de acesso: com XML de NF-e/NFC-e, a chave pode ser obtida do atributo Id de infNFe, mantendo apenas dígitos; com XML de cupom fiscal (CF-e), regra equivalente sobre o Id de infCFe.

COD_FILIAL e COD_FILIAL_DESTINO nas consultas a FILIAIS: valores recebidos são alinhados com preenchimento à esquerda até 6 posições antes da busca.

Número e série (NF-e/NFC-e): NF_NUMERO é normalizado com preenchimento à esquerda até 9 posições; com XML, nNF e serie do grupo ide substituem número e série vindos do payload; para determinadas séries numéricas curtas, a série pode ser completada à esquerda até 3 posições.

RECEBIMENTO e natureza interna: quando ausente no payload, pode ser definido como 0; com XML de NF, pode ser derivado de tpNF do ide. O código interno de natureza de operação gravado vem de LOJAS_NATUREZA_OPERACAO (NATUREZA_SAIDA ou NATUREZA_ENTRADA conforme o sentido definido por RECEBIMENTO).

QTDE_TOTAL (NF-e/NFC-e): com XML, recalculada pela soma das quantidades comerciais (qCom) dos itens.

Totais e valores (NF-e/NFC-e): com XML, valores como totais da nota, frete, seguro, descontos, produtos e tributos aproximados podem ser lidos de ICMSTot, transp e nós relacionados, substituindo os valores enviados apenas no payload.

Datas de emissão e autorização: com XML, EMISSAO, DATA_HORA_EMISSAO, DATA_HORA_SAIDA e dados de protocolo/autorização podem ser obtidos de dhEmi, dhRecbto e nProt conforme presença do protocolo.

PROTOCOLO_AUTORIZACAO_NFE: quando o protocolo tem mais de 15 caracteres e os dois caracteres imediatamente após os primeiros cinco são 00, esses dois caracteres são removidos (concatenação do prefixo de cinco caracteres com o sufixo a partir do oitavo caractere da string original).

OBS da nota (NF-e/NFC-e): pode concatenar texto montado a partir de notas referenciadas no XML, o campo OBS do payload e o conteúdo de infCpl quando existir.

TIPO_ORIGEM: quando vazio, recebe valor padrão conforme o tipo de operação da rotina (venda, troca, transferência, reserva, devolução ou outro); há regras adicionais que alteram TIPO_ORIGEM, cliente, filial de destino e cadastros de clifor conforme combinação de natureza de operação e tipo de origem.

Cupom fiscal (modelos fora de 55/65): entre outras alterações, TERMINAL pode ser completado à esquerda até 3 posições; SERIE_NF pode ser fixada em valor constante de cupom; NF_NUMERO e série podem vir de nCFe e nserieSAT quando há XML; GUID_VENDA_SAT é derivado por hash a partir de CO; totais e descontos podem ser lidos do XML do cupom em detrimento do payload.

Tratamento de retorno

Sucesso: Mensagem igual a OK e Mensagem Detalhada indicando registro com sucesso, com XML preenchido conforme o ramo executado.
Falha: Mensagem ERROR e Mensagem Detalhada com o texto da exceção (validação, filial não encontrada, natureza ausente, etc.).

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Endpoint (API)	Validação e filiais	Deve rejeitar quando `COD_FILIAL` ou cadastro em `LOJAS_VAREJO` não existir, ou quando `NATUREZA_OPERACAO_CODIGO` estiver vazia.	Mensagem de erro detalhada no retorno.
Endpoint (API)	Modelo fiscal	Deve executar o ramo de NF-e/NFC-e ou cupom conforme `NF_MODELO` e retornar XML no array de resposta em sucesso.	`Mensagem` `OK` e `XML` preenchido.