LojaReservaEntrada

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Reserva Entrada)
Biblioteca	wosk_loja_reserva_entrada
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 Reserva Entrada (LINX).

Descrição

Este serviço de retorno de reserva (entrada) recebe dados pelo endpoint, valida produtos quando informados e atualiza reserva e itens no LINX quando a natureza de operação corresponde ao fluxo de retorno.
Não há envio ao ILLI no arquivo analisado; a persistência ocorre em LOJA_RESERVA e LOJA_RESERVA_PRODUTO.

Endpoint (API)

O endpoint valida o payload, resolve FILIAL via FILIAIS, exige NATUREZA_OPERACAO_CODIGO e, para o código configurado para retorno de reserva (entrada), executa atualização em LOJA_RESERVA e zera quantidades e valores nos itens de LOJA_RESERVA_PRODUTO conforme o método interno analisado.

• Chamada: Requisição HTTP
• Recurso: /bibliotecas/c3ae9fe6-81b8-4b84-a5a2-93364cfee98d/wosk_loja_reserva_entrada
• 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 de origem; o processamento deste endpoint não utiliza este campo.
COD_FILIAL	string	sim	Código da filial (consulta em FILIAIS).
NATUREZA_OPERACAO_CODIGO	string	sim	Natureza fiscal; valor 1913 aciona o fluxo de retorno de reserva (entrada).
NUMERO	string	condicional	Número da reserva (NUMERO_RESERVA); obrigatório no ramo 1913.
CODIGO	number/string	não	Identificador auxiliar no payload; não referenciado no registra reserva de entrada analisado.
DATA_EMISSAO, DATA_ENTREGA	string (datetime)	sim	DATA_EMISSAO define ENCERRAMENTO no cabeçalho em LOJA_RESERVA no fluxo 1913 (apenas a parte de data, com hora fixada em 00:00:00). DATA_ENTREGA não é lida no registra reserva de entrada analisado.
NUMERO_NF, SERIE_NF	number	sim	Número e série da NF de retorno gravados em NUMERO_NF_RETORNO e SERIE_NF_RETORNO.
QTDE_TOTAL, VALOR_TOTAL	number/string	não	Totais informados no payload; no retorno o cabeçalho é atualizado com totais zerados pelo fluxo.
CODIGO_CLIENTE	string	não	Cliente no contexto da operação.
VENDEDOR	string	não	Vendedor no contexto da operação.
CODIGO_TAB_PRECO	string	não	Tabela de preço; usada em valida os produtos quando há PRODUTOS.
UF_FILIAL, UF_CLIENTE	string (2)	não	UFs de contexto; não utilizadas no processamento analisado.
XML	string	não	XML da NF-e; o processamento deste endpoint não interpreta o XML.
ID_EXCECAO_IMPOSTO	string	não	Exceção de imposto no nível do payload; itens podem trazer ID_EXCECAO_IMPOSTO próprio.
INSUMO	bool/string	não	Não deve ser informado como verdadeiro no fluxo 1913 (erro se preenchido).
PRODUTOS	array de objetos	condicional	Itens com CODIGO_BARRA, QTDE, PRECO; quando informado, validação via valida os produtos da wosk_loja_venda (a atualização de itens no banco segue todas as linhas de LOJA_RESERVA_PRODUTO da reserva).
ITEM, ID_EXCECAO_IMPOSTO (por item)	number/string	não	Metadados do item no payload.

Exemplo de payload enviado para o endpoint (JSON):

{
  "XML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\"><NFe>...</NFe><protNFe>...</protNFe></nfeProc>",
  "key": "df9b5d7f-da04-42f1-80b2-6b6bbbc39152",
  "CODIGO": 1397303,
  "NUMERO": "I0391160",
  "eventId": "5ff63eb3-a6dd-4e49-b8a4-c8859c44d6e2",
  "PRODUTOS": [
    {
      "ITEM": 1,
      "QTDE": 1,
      "PRECO": 797,
      "CODIGO_BARRA": "757501038M",
      "ID_EXCECAO_IMPOSTO": "15179"
    },
    {
      "ITEM": 2,
      "QTDE": 1,
      "PRECO": 447,
      "CODIGO_BARRA": "7575314172G",
      "ID_EXCECAO_IMPOSTO": "15179"
    }
  ],
  "SERIE_NF": 55,
  "VENDEDOR": "E084",
  "NUMERO_NF": 7189,
  "UF_FILIAL": "BA",
  "COD_FILIAL": "000483",
  "QTDE_TOTAL": 2,
  "UF_CLIENTE": "BA",
  "VALOR_TOTAL": "1244",
  "DATA_EMISSAO": "2026-03-30 15:57:48",
  "DATA_ENTREGA": "2026-03-30 15:57:48",
  "CODIGO_CLIENTE": "48696463404",
  "CODIGO_TAB_PRECO": "LM",
  "ID_EXCECAO_IMPOSTO": "",
  "NATUREZA_OPERACAO_CODIGO": "1913"
}

Operações com Dados

No fluxo principal do endpoint:

• Validação: validação base (valida os dados).
• Produtos: quando PRODUTOS está informado, delegação para valida os produtos da biblioteca.
• Filial: consulta em FILIAIS pelo COD_FILIAL; preenchem-se FILIAL e COD_CLIFOR.
• Natureza 1913: rejeita insumo; exige NUMERO da reserva; executa registra reserva de entrada, que localiza LOJA_RESERVA, atualiza o cabeçalho e, para cada linha existente em LOJA_RESERVA_PRODUTO da reserva, aplica atualização de quantidades e valores.

Tratamento de Dados

Modificações explícitas aplicadas aos dados de entrada ou aos registros atualizados:

• Consulta de filial: COD_FILIAL com preenchimento à esquerda até 6 posições antes da busca em FILIAIS.
• Validação de produtos (venda): CODIGO_TAB_PRECO com preenchimento à esquerda até 2 caracteres; itens mesclados com PRODUTO, COR_PRODUTO, GRADE, TAMANHO a partir de PRODUTOS_BARRA e DEMARCADO via busca preço demarcado.
• LOJA_RESERVA (cabeçalho): ENCERRAMENTO derivado apenas da parte de data de DATA_EMISSAO; QTDE_TOTAL e VALOR_TOTAL definidos como zero; NUMERO_NF_RETORNO com preenchimento à esquerda até 9 posições a partir de NUMERO_NF; SERIE_NF_RETORNO a partir de SERIE_NF; DATA_PARA_TRANSFERENCIA com data/hora corrente do processamento.
• LOJA_RESERVA_PRODUTO (itens): para cada produto/cor já existente da reserva, definem-se VALOR, QTDE_SAIDA e PRECO1 como zero, colunas EN1–EN48 como zero e DATA_PARA_TRANSFERENCIA com data/hora corrente (não usa apenas as linhas enviadas em PRODUTOS para localizar registros).

Tratamento de retorno

Sucesso: Mensagem OK e mensagem detalhada de sucesso. Falha: ERROR com texto da exceção (validação, filial, natureza, insumo indevido, reserva não encontrada, etc.).

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Endpoint (API)	Retorno de reserva	Com natureza 1913, deve localizar reserva e atualizar cabeçalho e itens sem insumo.	Registros atualizados no LINX ou erro documentado.