Integrações Sysmo S1 HubPromoção

API de Promoções

O que o Sysmo Integrador consulta no Nexus para cadastrar as promoções aprovadas no Sysmo S1

Testar agora
Serviço
verificando
Layout Sysmo
1.3
API Terceiros · 04/08/2025
Campanhas disponíveis iQuantas promoções o Integrador encontraria agora. Preenchido ao executar a chamada 1 no testador.
—
execute o testador
Sentido
Leitura
o Integrador consulta; o Nexus não envia

Como funciona

um ciclo a cada execução do Integrador

O caminho da promoção

1
O comprador envia a promoção ao ERP pelo NexusDepois de aprovada, ele clica em Enviar ao ERP, confere a prévia (o que vai, o que não vai e por quê) e confirma. Só então ela passa a existir para a API, com o código daquele envio.
2
O Sysmo Integrador consulta a APIEle roda no servidor do cliente e, de tempos em tempos, lista as campanhas, lê as ofertas, o rótulo do clube e os produtos.
3
O Sysmo S1 recebe a promoçãoCadastrada com o nome HUBPROMOÇÃO {número} - {nome}, agrupada por modalidade. Campanha já importada não é lida de novo.
4
O Nexus confirma sozinhoA carga diária do conector traz do S1 a promoção criada; o Nexus a reconhece pelo código do envio e marca a promoção como Enviada ao ERP.

As quatro chamadas do ciclo

todas GET, JSON
1 · Campanhas/campanha
2 · Ofertas da campanha/campanha/{codigo}/ofertas
3 · Rótulo do clube/tipo_oferta
4 · Produto da oferta…/oferta/{oferta}/produtos

Regras de retirada

Retirada do ERPsai com excluido: true e as lojas por 30 dias
Reenvio depois de retirarcódigo novo (envio × 10^9 + número)
Vigência encerradasome da lista sozinha

Dados e origem

o que cada informação é, de onde vem e como é gerada

Campanha

= promoção do Nexus
O que éuma promoção aprovada
Código iÉ o número da promoção que aparece na tela Promoções (no 1º envio); num reenvio depois de retirar do ERP, vira envio × 10^9 + número (ex.: 2000000132). O S1 guarda esse código como código externo e o usa no nome da promoção.código do envio
Nome e períodocabeçalho da promoção
Lojas iCódigos das lojas no ERP. Promoção sem loja marcada vale para todas as lojas em operação (ativas e com venda nos últimos 90 dias).lojas da promoção, código do ERP

Como é gerada

Entra na lista quando está aprovada, com todos os itens conferidos e data final a partir de hoje. Promoção que já foi cadastrada à mão no ERP (nome começando pelo número dela) não entra, para não duplicar. Consultada na hora de cada chamada, sem cópia intermediária.

Oferta

= item da promoção
O que éum item conferido da promoção
Tipo iA mecânica do item vira o tipo da Sysmo: Preço por → normal; Preço por com Clube → fidelidade; Desconto % → normal com preço calculado; Leve e pague → pague-leve; A partir de → atacado.pela mecânica do item
Preço de iNão é o preço gravado no item: é o preço de venda vigente nas lojas da promoção, sincronizado do ERP pelo conector. É contra ele que o S1 valida o desconto.preço de venda vigente
Preço da ofertacoluna Por (ou Clube)
Limite por clientecoluna Limite; 0 = sem limite

Como é gerada

Só itens vendáveis com produto ativo. Item que o S1 recusaria fica de fora e vai para o registro do serviço: preço da oferta igual ou maior que o preço vigente, preço zerado, código de produto com mais de 9 dígitos, "a partir de" igual a 1 ou só com preço de clube.

Produto e clube

Produto iCódigo do produto no ERP, igual ao do cadastro do Sysmo S1 (o Nexus recebe o cadastro de produtos do ERP pelo conector). Só o produto principal; família e associados vão vazios para nunca repetir produto na campanha.código do produto no ERP
Descriçãocadastro de produtos
Rótulo do clube iO clube marcado como usado na integração em Promoções › Configurações › Clube de fidelidade do Nexus, escolhido da lista de personas do S1 ou digitado. Precisa ser igual à descrição da persona do clube no S1; sem persona igual, as ofertas de fidelidade não entram. Sem clube marcado, vale o rótulo reserva da instalação do serviço.Promoções › Configurações

Situação da campanha

Disponívellistada; o S1 ainda não copiou
Importadao conector trouxe a cópia; promoção Enviada ao ERP
Retiradareaberta antes da cópia; sai como excluída

Endpoints

respostas em JSON · datas AAAA-MM-DD · preços com 2 casas, quantidades com 3
GET

/campanha?step=INTEGRACAO

Campanhas disponíveis. Sem paginação; o Integrador lê só a primeira página.

campotiposignificado
codigotextocódigo do envio (1º = número da promoção no Nexus)
nometextonome da promoção
inicio, fimdatavigência; 00:00 do início a 23:59 do fim
excluidobooleanotrue = o S1 deve apagar o que criou
lojaslistacódigos das lojas no ERP
segmentoslistasempre vazia nesta versão
{ "count": 1, "next": null, "previous": null, "results": [ { "codigo": "132", "nome": "Finde - Varejo", "inicio": "2027-02-01", "fim": "2027-02-02",
                "excluido": false, "lojas": ["2", "3"], "segmentos": [] } ] }
GET

/campanha/{codigo}/ofertas?preenchidas=true&page=1

Ofertas da campanha, paginadas. count é o total de ofertas somando todas as páginas (o mesmo em todas); next traz a URL da próxima página ou null na última; previous, a da anterior ou null na primeira.

campotiposignificado
codigonúmeroidentificador da oferta
regra.tipotextonormal · fidelidade · pague-leve · atacado
regra.preco_denúmeropreço de venda vigente
regra.limite_por_clientenúmero0 = sem limite
regra (demais)númeropreco · preco_normal, preco_fidelidade · quantidade_pague, quantidade_leve · preco_varejo, preco_atacado, quantidade_atacado
cluster, grupoobjetosempre null
{ "count": 2, "next": null, "previous": null, "results": [
  { "codigo": 12446, "regra": { "tipo": "fidelidade", "preco_de": 21.99, "preco_normal": 21.99, "preco_fidelidade": 16.99, "limite_por_cliente": 0 }, "cluster": null, "grupo": null },
  { "codigo": 12531, "regra": { "tipo": "atacado", "preco_de": 9.99, "preco_varejo": 9.99, "preco_atacado": 7.49, "quantidade_atacado": 12, "limite_por_cliente": 0 }, "cluster": null, "grupo": null } ] }
GET

/tipo_oferta

Rótulo do clube de benefícios. O S1 procura uma persona com descrição igual a label (com mais de uma igual, usa a de maior código). Vem do clube marcado no Nexus em Promoções › Configurações › Clube de fidelidade; sem ele, do rótulo reserva da instalação; sem os dois, a resposta é [] e as ofertas de clube não entram.

[ { "codigo": "fidelidade", "label": "CLUBE NEXUS" } ]
GET

/campanha/{codigo}/oferta/{oferta}/produtos

Produto principal da oferta. produtos_familia e produtos_associados sempre vazios.

{ "count": 1, "next": null, "previous": null, "results": [ { "produto": { "codigo": "48861", "descricao": "DESOD DOVE 200ML FEM INVISIBLE DRY" },
                "tipo_produto": "principal", "produtos_familia": [], "produtos_associados": [] } ] }
GET

/saude

Estado do serviço, sem credencial. 200 com serviço e base disponíveis; 503 caso contrário.

{ "ok": true, "versao": "0.1.0", "banco": "ok" }

Conexão e segurança

o que a Sysmo precisa receber de cada cliente

Endereço

URL do serviço—
ProtocoloHTTPS, porta 443
Um serviço por cliente iCada rede tem o seu endereço e a sua credencial. O Integrador de um cliente nunca enxerga os dados de outro.endereço e credencial próprios
FormatoGET · JSON · UTF-8

Credencial

CabeçalhoX-Api-Key: {token}
AlternativaAuthorization: Basic usuário:token
Sem credencial401
Limite iProteção contra uso indevido. O ciclo normal do Integrador usa poucas dezenas de chamadas.600 requisições por minuto
Livre de credencial/saude e esta página

Referências da Sysmo

Central de Ajuda · HubPromoção
Layout de integraçãoAPI Terceiros v1.3

No cliente

Novo cadastro de promoções ativo no S1 e Integrador com saída para a internet (ele precisa alcançar a URL acima).

Como a API foi desenvolvida

arquitetura, acesso aos dados e garantias

Arquitetura

Serviçopróprio, separado do sistema web
TecnologiaNode.js · TypeScript
Implantaçãoum container por cliente
Monitoramento/saude a cada 30 s

Por que separado

Tudo o que é específico do Sysmo (nomes de campos, tipos de oferta, regras de validação) fica neste serviço. O Nexus continua independente de ERP; trocar ou somar um ERP é outro serviço, não uma mudança no sistema.

Acesso aos dados

Fontebanco do Nexus do cliente
Usuário iUm usuário de banco exclusivo da integração, que só pode executar três consultas prontas (campanhas, ofertas, produto). Não lê tabelas nem outros dados do cliente.exclusivo e restrito
ConexãoTLS com certificado verificado
Escritasó contadores de consulta

O que a consulta faz

Monta a campanha a partir da promoção aprovada, das lojas dela e do preço de venda vigente de cada produto; traduz cada item para o tipo de oferta da Sysmo; e registra quando o Integrador leu cada campanha.

Garantias e verificação

Contratolayout Sysmo API Terceiros 1.3
Testes automatizadostradução, paginação, credencial, rotas
Registrocada chamada e cada item retido
Confirmaçãopelo conector, a cada 15 min

Homologação com a Sysmo

Cabeçalho que o Integrador envia, intervalo de consulta, ofertas de fidelidade só com preço de clube, valor do pague-leve, atacado × escalonada e a descrição exata da persona do clube.

Testar

monte a chamada, envie e veja a resposta; os valores entre chaves vêm do ambiente

Coleção

Ambiente

Requisição

1 · Campanhas
GET
chavevalor
cabeçalhovalor

Resposta

———
Clique em Enviar ou em "Executar coleção inteira".

O testador chama este mesmo serviço com a credencial informada; nada fica gravado além dos contadores de consulta, os mesmos que o Integrador atualiza. O token não é guardado: vale só enquanto a aba está aberta.