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/20261.1Maykon/GustavoEstruturaçã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
Estrutura

A estrutura abaixo corresponde ao conteúdo de altopayload.json nível(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)
VENDEDORESeventId arraystring (identificador do evento)

Cada elemento de VENDAS[]
CampoTipo
CANCELAMENTOSCO arraystring
CANCELAMENTO_PRAZOXML arraystring (conteúdo XML da NF-e / NFC-e)
FECHAMENTO_CAIXADATAstring (data/hora da venda, ex.: AAAA-MM-DD HH:MM:SS)
MOBILEstring
TICKETstring
DESCONTOstring
NF_CHAVEstring
NF_SERIEnumber
PRODUTOS array de objetos (estrutura na tabela PRODUTOS[])
TERMINALnumber
VENDEDORstring
NF_MODELOnumber
NF_NUMEROnumber
UF_FILIALstring
XML_TROCAstring
COD_FILIALstring
DATA_TROCAstring
PAGAMENTOSarray de objetos (estrutura na tabela PAGAMENTOS[])
QTDE_TOTALnumber
UF_CLIENTEstring
VALOR_PAGOnumber
VALOR_FRETEnumber
VALOR_TROCAnumber
DATA_VITRINEstring
VALOR_VITRINEnumber
CODIGO_CLIENTEstring
NF_CHAVE_TROCAstring
NF_SERIE_TROCAstring
OPERACAO_VENDAstring
PRODUTOS_TROCAarray (no exemplo vazio; itens com a mesma estrutura de PRODUTOS[] quando informados)
NF_MODELO_TROCAstring
NF_NUMERO_TROCAstring
UF_FILIAL_TROCAstring
CODIGO_TAB_PRECOstring
LANCAMENTO_CAIXAstring
PRODUTOS_VITRINEarray (no exemplo vazio)
QTDE_TROCA_TOTALnumber
UF_CLIENTE_TROCAstring
ID_PEDIDO_VITRINEstring
VALOR_VENDA_BRUTAstring
ID_EXCECAO_IMPOSTOstring
QTDE_VITRINE_TOTALnumber
CODIGO_CLIENTE_TROCAstring
NUMERO_TITULO_VITRINEstring
CODIGO_TAB_PRECO_TROCAstring
VALOR_DESCONTO_VITRINEnumber
CODIGO_TAB_PRECO_VITRINEstring
ID_EXCECAO_IMPOSTO_TROCAstring
NATUREZA_OPERACAO_CODIGOstring
NATUREZA_OPERACAO_CODIGO_TROCAstring

Cada elemento de VENDAS[].PRODUTOS[]
CampoTipo
ITEMnumber
QTDEnumber
CUSTOnumber
VENDAnumber
CODIGO_EANstring
QTDE_BRINDEnumber
VALOR_TOTALnumber
CODIGO_BARRAstring
DESCONTO_ITEMnumber
PRECO_LIQUIDOnumber
ID_EXCECAO_IMPOSTOstring
RATEIO_DESCONTO_VENDAnumber

Cada elemento de VENDAS[].PAGAMENTOS[]
CampoTipo
ITEMnumber
TXIDstring
TROCOnumber
VALORnumber
PARCELASnumber
TIPO_PGTOstring
ENDTOENDIDstring
VENCIMENTOstring (data/hora, ex.: AAAA-MM-DD HH:MM:SS)
DATA_HORA_TEFstring (data/hora, ex.: AAAA-MM-DD HH:MM:SS)
NUMERO_TITULOstring
COD_FORMA_PGTOstring
REDE_CONTROLADORAstring
CODIGO_ADMINISTRADORAstring
NUMERO_APROVACAO_CARTAOstring

Exemplo de payload enviadoalinhado paraao payload.json (o campo XML foi omitido no trecho; no envio real contém o endpointXML (JSON)completo —da esqueleto:nota):

{
  "key": "<API_KEY_SE_APLICAVEL>"df9b5d7f-da04-42f1-80b2-6b6bbbc39152",
  "VENDAS": [
    {
      "CODIGO_FILIAL"CO": "000001"393-26085069707-48",
      "TERMINAL"XML": "001"<XML da NF-e conforme autorização>",
      "DATA": "<DATA_HORA>2026-03-26 15:59:50",
      "MOBILE": "0",
      "TICKET": "",
      "DESCONTO": "0",
      "NF_CHAVE": "35260335943604005620650650000199011642134767",
      "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": "<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"
        }
      ],
      "PRODUTOS"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-530b-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.
Voltar ao topo