Ir para o conteúdo principal

LojaVenda (STATUS: DOCUMENTADO)

Documentação Técnica
Nome do cliente OSKLEN
Nome do projeto Integração LINX (Venda PDV)
Biblioteca wosk_loja_venda
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 Venda (LINX).
26/03/2026 1.1 Maykon/Gustavo Estruturação de Dados: todos os campos do payload.json (raiz, VENDAS, PRODUTOS, PAGAMENTOS) e exemplo completo.

Descrição

Este serviço de venda do PDV recebe estruturas aninhadas (venda, pagamentos, produtos, vendedores, cancelamentos, fechamento de caixa, etc.) e persiste no banco LINX em tabelas como LOJA_VENDA, LOJA_VENDA_PGTO, LOJA_CAIXA_LANCAMENTOS, ILLIMITAR_PDV_CONTROLE_VENDA e demais entidades tratadas pelos métodos internos.
Não há chamada HTTP ao ILLI no arquivo analisado; o fluxo é de gravação e regras de negócio no LINX.

Endpoint (API)

O método principal valida o payload raiz e processa blocos opcionais: VENDAS (com validação de produtos quando informados, comissão de vendedor, lançamento de caixa, controle de ticket, pagamentos e parcelas, venda, vendedores e produtos da venda), VENDEDORES, CANCELAMENTOS, CANCELAMENTO_PRAZO e FECHAMENTO_CAIXA, cada um com try/catch próprio e retorno de Mensagem/Mensagem Detalhada no sub-objeto.

  • Chamada: Requisição HTTP
  • Recurso: /bibliotecas/2cd82f28-3bbf-4f82-bbd8-383f7a912b4f/wosk_loja_venda
  • Método HTTP: POST
Estruturação de Dados

A estrutura abaixo corresponde ao conteúdo de payload.json (campos, tipos e aninhamento conforme o exemplo).

Objeto raiz do payload
Campo Tipo
key string (identificador)
VENDAS array de objetos (cada elemento descrito na tabela seguinte)
eventId string (identificador do evento)

Cada elemento de VENDAS[]
Campo Tipo
CO string
XML string (conteúdo XML da NF-e / NFC-e)
DATA string (data/hora da venda, ex.: AAAA-MM-DD HH:MM:SS)
MOBILE string
TICKET string
DESCONTO string
NF_CHAVE string
NF_SERIE number
PRODUTOS array de objetos (estrutura na tabela PRODUTOS[])
TERMINAL number
VENDEDOR string
NF_MODELO number
NF_NUMERO number
UF_FILIAL string
XML_TROCA string
COD_FILIAL string
DATA_TROCA string
PAGAMENTOS array de objetos (estrutura na tabela PAGAMENTOS[])
QTDE_TOTAL number
UF_CLIENTE string
VALOR_PAGO number
VALOR_FRETE number
VALOR_TROCA number
DATA_VITRINE string
VALOR_VITRINE number
CODIGO_CLIENTE string
NF_CHAVE_TROCA string
NF_SERIE_TROCA string
OPERACAO_VENDA string
PRODUTOS_TROCA array (no exemplo vazio; itens com a mesma estrutura de PRODUTOS[] quando informados)
NF_MODELO_TROCA string
NF_NUMERO_TROCA string
UF_FILIAL_TROCA string
CODIGO_TAB_PRECO string
LANCAMENTO_CAIXA string
PRODUTOS_VITRINE array (no exemplo vazio)
QTDE_TROCA_TOTAL number
UF_CLIENTE_TROCA string
ID_PEDIDO_VITRINE string
VALOR_VENDA_BRUTA string
ID_EXCECAO_IMPOSTO string
QTDE_VITRINE_TOTAL number
CODIGO_CLIENTE_TROCA string
NUMERO_TITULO_VITRINE string
CODIGO_TAB_PRECO_TROCA string
VALOR_DESCONTO_VITRINE number
CODIGO_TAB_PRECO_VITRINE string
ID_EXCECAO_IMPOSTO_TROCA string
NATUREZA_OPERACAO_CODIGO string
NATUREZA_OPERACAO_CODIGO_TROCA string

Cada elemento de VENDAS[].PRODUTOS[]
Campo Tipo
ITEM number
QTDE number
CUSTO number
VENDA number
CODIGO_EAN string
QTDE_BRINDE number
VALOR_TOTAL number
CODIGO_BARRA string
DESCONTO_ITEM number
PRECO_LIQUIDO number
ID_EXCECAO_IMPOSTO string
RATEIO_DESCONTO_VENDA number

Cada elemento de VENDAS[].PAGAMENTOS[]
Campo Tipo
ITEM number
TXID string
TROCO number
VALOR number
PARCELAS number
TIPO_PGTO string
ENDTOENDID string
VENCIMENTO string (data/hora, ex.: AAAA-MM-DD HH:MM:SS)
DATA_HORA_TEF string (data/hora, ex.: AAAA-MM-DD HH:MM:SS)
NUMERO_TITULO string
COD_FORMA_PGTO string
REDE_CONTROLADORA string
CODIGO_ADMINISTRADORA string
NUMERO_APROVACAO_CARTAO string

Exemplo de payload alinhado ao payload.json (o campo XML foi omitido no trecho; no envio real contém o XML completo da nota):

{
  "key": "df9b5d7f-da04-42f1-6y8p-6b6bbbc39152",
  "VENDAS": [
    {
      "CO": "393-26085069707-48",
      "XML": "<XML da NF-e conforme autorização>",
      "DATA": "2026-03-26 15:59:50",
      "MOBILE": "0",
      "TICKET": "",
      "DESCONTO": "0",
      "NF_CHAVE": "35260335943604005620650650000788911642135207",
      "NF_SERIE": 65,
      "PRODUTOS": [
        {
          "ITEM": 1,
          "QTDE": 1,
          "CUSTO": 361.75,
          "VENDA": 1327,
          "CODIGO_EAN": "",
          "QTDE_BRINDE": 0,
          "VALOR_TOTAL": 1327,
          "CODIGO_BARRA": "7532118P",
          "DESCONTO_ITEM": 0,
          "PRECO_LIQUIDO": 1327,
          "ID_EXCECAO_IMPOSTO": "15323",
          "RATEIO_DESCONTO_VENDA": 0
        }
      ],
      "TERMINAL": 3,
      "VENDEDOR": "0833",
      "NF_MODELO": 65,
      "NF_NUMERO": 19901,
      "UF_FILIAL": "SP",
      "XML_TROCA": "",
      "COD_FILIAL": "000315",
      "DATA_TROCA": "",
      "PAGAMENTOS": [
        {
          "ITEM": 1,
          "TXID": "",
          "TROCO": 0,
          "VALOR": 1327,
          "PARCELAS": 6,
          "TIPO_PGTO": "I",
          "ENDTOENDID": "",
          "VENCIMENTO": "2026-04-25 15:59:50",
          "DATA_HORA_TEF": "2026-03-26 15:59:39",
          "NUMERO_TITULO": "343038320",
          "COD_FORMA_PGTO": "##",
          "REDE_CONTROLADORA": "REDC",
          "CODIGO_ADMINISTRADORA": "25",
          "NUMERO_APROVACAO_CARTAO": "343038320"
        }
      ],
      "QTDE_TOTAL": 1,
      "UF_CLIENTE": "SP",
      "VALOR_PAGO": 1327,
      "VALOR_FRETE": 0,
      "VALOR_TROCA": 0,
      "DATA_VITRINE": "",
      "VALOR_VITRINE": 0,
      "CODIGO_CLIENTE": "12800698802",
      "NF_CHAVE_TROCA": "",
      "NF_SERIE_TROCA": "",
      "OPERACAO_VENDA": "01",
      "PRODUTOS_TROCA": [],
      "NF_MODELO_TROCA": "",
      "NF_NUMERO_TROCA": "",
      "UF_FILIAL_TROCA": "SP",
      "CODIGO_TAB_PRECO": "00",
      "LANCAMENTO_CAIXA": "",
      "PRODUTOS_VITRINE": [],
      "QTDE_TROCA_TOTAL": 0,
      "UF_CLIENTE_TROCA": "SP",
      "ID_PEDIDO_VITRINE": "",
      "VALOR_VENDA_BRUTA": "1327",
      "ID_EXCECAO_IMPOSTO": "",
      "QTDE_VITRINE_TOTAL": 0,
      "CODIGO_CLIENTE_TROCA": "",
      "NUMERO_TITULO_VITRINE": "",
      "CODIGO_TAB_PRECO_TROCA": "00",
      "VALOR_DESCONTO_VITRINE": 0,
      "CODIGO_TAB_PRECO_VITRINE": "00",
      "ID_EXCECAO_IMPOSTO_TROCA": "",
      "NATUREZA_OPERACAO_CODIGO": "5102.2",
      "NATUREZA_OPERACAO_CODIGO_TROCA": ""
    }
  ],
  "eventId": "04b5b930-89po-446c-aead-b4a7935aaa08"
}
Tratamento de Dados

Inclui normalização de terminal, datas de venda e digitação, obtenção de comissão em LOJA_VENDEDORES, geração de sequências de caixa e ticket, persistência de pagamentos e parcelas, itens de venda e demais entidades conforme cada método setLoja* no código-fonte.

Tratamento de retorno

Cada bloco processado retorna Mensagem OK ou ERROR com detalhe; o array raiz é atualizado com o último resultado processado e devolvido após registro de auditoria.

Fluxo do Processo

Diagrama do processo


Critérios de Aceitação
Processo Subprocesso Descrição Situação esperada
Endpoint (API) Venda completa Com VENDAS[0] válido, deve gravar caixa, venda, pagamentos e produtos de forma consistente. Mensagem OK ou erro explícito.
Nenhum comentário
Voltar ao topo