Tabela de conteúdos
Integração com o Self-Checkout SZ
A integração mantém o self-checkout da SZ abastecido com o cadastro da loja: o ERP envia sozinho à SZ os produtos, os preços e as comandas sempre que um deles muda. O cliente passa a comanda e as etiquetas no totem, confere o peso na balança e paga ali mesmo, com os dados que o ERP mandou.
Cada alteração entra numa fila de envio, e uma tarefa do Agendador de Tarefas envia a fila à SZ a cada minuto. Assim a gravação no ERP e no Frente de Caixa não espera a resposta da SZ, e o que falhar é enviado de novo.
✅ Pré-Requisitos
- Token de integração da SZ, de homologação e de produção, gerado no Admin da SZ em Self-Checkout → Integrações → Tokens de integração do ERP, e a URL da API da SZ de cada ambiente;
- Tabela de preço do self-checkout cadastrada no ERP, com os preços dos produtos vendidos no totem;
- Agendador de Tarefas do ERP em execução no servidor;
- Frente de Caixa com a conexão do ERP configurada, para que as comandas e os preços alterados no caixa entrem na fila.
⚙️ Parâmetros
Na PRX004498, inclua uma configuração com a parceira SZ Self-Checkout:
| Campo | Descrição |
|---|---|
| Parceira | SZ Self-Checkout. |
| Ambiente Ativo | Homologação ou Produção: define qual URL e qual token são usados no envio. |
| URL (Homologação / Produção) | Endereço da API da SZ, por exemplo https://homolog-totem-saojose.szsolucoes.com.br/api/integracoes/erp/v1. |
| Token (Homologação / Produção) | Token de integração gerado no Admin da SZ. |
| E-mail de Aviso de Falha | Quem recebe o aviso quando a SZ recusar o token. Mais de um e-mail, separados por ponto e vírgula (;). |
| Configurações Adicionais | Ajustes do envio, em JSON (tabela abaixo). |
As Configurações Adicionais aceitam:
| Chave | Obrigatória | Padrão | Descrição |
|---|---|---|---|
CodigoTabelaPreco | Sim | Número da tabela de preço do self-checkout. | |
TamanhoLote | Não | 100 | Quantos produtos, preços ou comandas vão em cada chamada à SZ, de 1 a 500. |
MinutosLimiteDifusao | Não | 10 | Minutos que um envio sem resposta pode levar antes de ser repetido. |
SegundosTimeout | Não | 10 | Segundos de espera pela resposta da SZ em cada chamada. |
Exemplo: {“CodigoTabelaPreco”: 5, “TamanhoLote”: 100}
Ao gravar, a tela confere a configuração e recusa:
- URL ou token vazios no ambiente ativo;
- Configurações Adicionais fora do formato JSON;
- tabela de preço não informada ou inexistente;
- tamanho do lote fora de 1 a 500, ou tempos menores que 1.
Sem e-mail de aviso de falha, a tela só alerta: a integração funciona, mas ninguém é avisado quando o token for recusado.
Para acompanhar as chamadas à SZ, ligue o parâmetro de sistema INTWSLOG_ATIVA_LOGS_DB: cada envio fica registrado na PRX002798, com o endereço, o conteúdo enviado, a resposta e o código de retorno (o token aparece mascarado).
📦 Cadastro do Produto
No Cadastro de Itens (PRX036716), os campos usados pelo totem:
| Campo | Aba | Descrição |
|---|---|---|
| Tolerância de Peso (%) | Ficha Técnica → Medidas | Margem aceita na conferência de peso do totem, para mais ou para menos, de 0 a 100% do peso unitário. Vazio exige o peso exato. |
| Pesável | Ficha Técnica → Medidas | Produto a granel, pesado na balança à frente do totem e escolhido na tela de pesquisa. |
| Fracionável | Ficha Técnica → Medidas | A quantidade vem da etiqueta. Desmarcado, a quantidade é sempre 1. |
| Venda somente para maiores de 18 anos | Características Especiais | O totem pede ao cliente que confirme ter 18 anos ou mais antes de incluir o item. |
O produto vai à SZ com o Código do Material, a descrição, a unidade de medida, o peso unitário (em kg, quando a unidade não é KG) e a tolerância convertida em kg.
🔄 Como Funciona
► O que entra na fila de envio
- Produto: a gravação do item que muda algum dado enviado à SZ (descrição, unidade, peso, situação e os campos acima). O item em aprovação só entra depois de aprovado;
- Preço: a gravação, a exclusão, o reajuste e a cópia de preços da tabela do self-checkout, com vigência até o dia; a gravação ou a exclusão da própria tabela; e a importação de produtos no Frente de Caixa, para o produto novo ou com preço de venda alterado;
- Comanda: a gravação da pré-venda no Frente de Caixa e, no aplicativo do garçom e do buffet, gravar, cancelar, cancelar item e transferir itens entre contas.
O preço enviado é o preço de venda do produto no Frente de Caixa. A comanda vai com todos os itens, inclusive os cancelados; a comanda fechada vai sem itens.
► Tarefas do Agendador de Tarefas
| Tarefa | Quando agendar | O que faz |
|---|---|---|
| Envio ao Self-Checkout SZ | A cada minuto | Envia à SZ os produtos, preços e comandas da fila, um lote por tipo. |
| Preços do Self-Checkout com Vigência Iniciada no Dia | Uma vez por dia, no início do dia | Põe na fila os preços da tabela do self-checkout cuja vigência começa no dia. |
| Carga Inicial do Self-Checkout | Uma vez, na implantação | Põe na fila todos os produtos ativos e os preços deles na tabela do self-checkout. |
► Passo-a-passo da implantação
- Gere o token no Admin da SZ e grave a configuração na PRX004498, primeiro no ambiente de Homologação;
- Preencha no Cadastro de Itens os campos do totem nos produtos vendidos no self-checkout;
- Ligue o INTWSLOG_ATIVA_LOGS_DB e agende as tarefas Envio ao Self-Checkout SZ e Preços do Self-Checkout com Vigência Iniciada no Dia;
- Execute uma vez a tarefa Carga Inicial do Self-Checkout e acompanhe os envios na PRX002798;
- Conferido em homologação, troque o Ambiente Ativo para Produção.
► Retorno da SZ
A SZ responde cada produto, preço ou comanda separadamente:
| Resposta | O que acontece na fila |
|---|---|
| Aceito | Sai da fila. Se o objeto foi alterado durante o envio, volta para ser enviado de novo. |
| Rejeitado | Fica recusado, com o motivo dado pela SZ. Volta a ser enviado na próxima alteração do objeto. |
| Chamada inválida (400) | Todos os objetos da chamada ficam recusados, com a mensagem da SZ. |
| Token recusado (401) | Os objetos voltam a aguardar envio, a rodada para e o E-mail de Aviso de Falha recebe o aviso. O envio só volta depois de corrigir o token na PRX004498. |
| SZ fora do ar, erro ou sem resposta no tempo limite | Os objetos voltam a aguardar envio e são enviados de novo na rodada seguinte. |
❗ Problemas Comuns
| Situação | O que fazer |
|---|---|
| Nada é enviado | Confira se a configuração da PRX004498 foi gravada no estabelecimento da loja e se a tarefa Envio ao Self-Checkout SZ está agendada e o Agendador em execução. |
| E-mail “token recusado” | Gere um novo token no Admin da SZ e grave-o na PRX004498, no ambiente ativo. |
| Produto recusado pela SZ | O motivo aparece na resposta da chamada, na PRX002798. Corrija o cadastro do item: a gravação o põe de novo na fila. |
| Preço não chega ao totem | Confira se o preço é da tabela informada em CodigoTabelaPreco e se a vigência já começou. |
| Comanda sem itens no totem | A comanda está fechada ou o cartão não tem comanda aberta no Frente de Caixa. |