Ir para o conteúdo principal

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

wosk_loja_nota_fiscal.drawio.jpg


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