LojaNotaFiscal (STATUS: DOCUMENTADO)

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

Campos centrais do payload (referência ao fluxo principal; validações adicionais vêm do serviço base e métodos auxiliares)
Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Chave de API quando exigida pela plataforma de bibliotecas.
`COD_FILIAL`	string	sim	Código da filial (padronizado para busca em `FILIAIS`).
`PRODUTOS`	array	condicional	Quando informado, passa por validação específica de produtos antes do processamento principal.
`XML`	array	condicional	Quando informado, passa por validação específica de XML antes do processamento principal.
`COD_FILIAL_DESTINO`	string	não	Quando informado, resolve segunda filial e cadastro em `LOJAS_VAREJO` para destino.
`NATUREZA_OPERACAO_CODIGO`	string	sim	Obrigatório para seguir o fluxo de geração de documento.
`NF_MODELO`	number	sim	Define o ramo: valores 55 ou 65 usam geração de nota fiscal; demais usam fluxo de cupom fiscal.

Exemplo de payload enviado para o endpoint (JSON):

{
  "key": "<API_KEY_SE_APLICAVEL>",
  "COD_FILIAL": "000001",
  "COD_FILIAL_DESTINO": "",
  "NATUREZA_OPERACAO_CODIGO": "<CODIGO>",
  "NF_MODELO": 55,
  "PRODUTOS": [],
  "XML": []
}

Tratamento de Dados

No fluxo principal, após validações:

Filial: COD_FILIAL é localizado em FILIAIS; preenchem-se FILIAL, CGC_CPF e, se vazio, COD_CLIFOR.
Loja: LOJAS_VAREJO é consultada por FILIAL; preenchem-se CODIGO_FILIAL e GERENTE_LOJA.
Destino: com COD_FILIAL_DESTINO, resolve-se segunda filial em FILIAIS e LOJAS_VAREJO para FILIAL_DESTINO e CODIGO_FILIAL_DESTINO quando aplicável.
Documento: para NF_MODELO 55 ou 65 chama-se a rotina de montagem de nota fiscal; caso contrário chama-se a rotina de cupom fiscal; o resultado alimenta XML no array de retorno.
Persistência: gravações e detalhamento por item, impostos e tabelas auxiliares ocorrem dentro das rotinas de montagem (incluindo estruturas como LOJA_NOTA_FISCAL e correlatas conforme implementação no arquivo-fonte).

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.