SANDBOXAmbiente de testes — pagamentos em modo teste, servidores simulados. Nada aqui é real.

Para desenvolvedores

JPSIS Ads — API de anúncios

A API de anúncios deixa os sistemas da JPSIS (RadioBox, SecBox, MikroSDN, MikroERP e os próximos) mostrarem anúncios do ecossistema dentro da própria tela. Use para divulgar outros produtos da plataforma, lançamentos, promoções ou parceiros.

Os anúncios são cadastrados no painel admin → Anúncios, com imagem, texto, botão, destino, período e em quais sistemas aparecem. Os sistemas só perguntam ao hub "tem anúncio para mim?" e desenham o que vier.

Como funciona

  1. O navegador pede anúncios ao backend do próprio sistema (ex.: GET /api/anuncios?placement=banner).
  2. O backend consulta o hub com o SDK jpsis-ads.ts, autenticado pelo certificado da licença, como no login e na API de pagamentos.
  3. O hub escolhe os anúncios elegíveis para aquele sistema e formato, sorteando pelo peso de cada um.
  4. O navegador desenha com o jpsis-ads-widget.js. A visualização só é contada quando o anúncio fica pelo menos 50% visível. O clique passa pelo hub, que registra e redireciona.
 navegador              backend do sistema                 jpsis.com.br
    │ GET /api/anuncios ──►  jpsisAds.get()  ─────────────►  /api/ads/v1/serve
    │                       ◄── { data: [anúncio] } ───────
    │ ◄── lista ────────────
    │ desenha + view_url (quando visível) ─────────────────►  /api/ads/v/<token>
    │ clique em click_url ─────────────────────────────────►  /api/ads/c/<token> → destino

Formatos (placement)

Formato Onde usar O que mostra
banner Topo de páginas, dashboards Faixa horizontal com imagem pequena, título, texto e botão
card Barra lateral, telas vazias Cartão com imagem 16:9, título, texto e botão
text Rodapés, listas, tela de login Uma linha discreta: "Anúncio · Título — texto · Saiba mais →"

Cada anúncio é cadastrado com os formatos em que pode aparecer.

Segmentação

O hub só entrega anúncios que passam em todas estas regras:

  • estão ativos e dentro do período (início/fim), quando houver;
  • aceitam o formato pedido;
  • estão liberados para o sistema que pediu (ou para todos);
  • não anunciam o próprio sistema — o RadioBox nunca mostra anúncio do RadioBox;
  • não anunciam um produto que o usuário já tem, quando o sistema informa o usuário (payToken). Por exemplo, quem já tem MikroERP não vê anúncio do MikroERP dentro do MikroSDN.

Entre os elegíveis, o sorteio usa o peso (1 a 100): um anúncio com peso 20 aparece cerca de duas vezes mais que um com peso 10.

SDK

Copie para o sistema os arquivos da pasta sdk/ (ou baixe pelos botões no topo desta página):

  • jpsis-ads.ts — backend (Node 20+), depende só de jose, com cache embutido.
  • jpsis-ads-widget.js — navegador, sem dependências, com tema claro e escuro.

Backend

import { JpsisAds } from "./jpsis-ads";
const jpsisAds = new JpsisAds(); // lê /etc/jpsis/license.json

app.get("/api/anuncios", async (req, res) => {
  const placement = ["banner", "card", "text"].includes(String(req.query.placement)) ? req.query.placement : "banner";
  const list = await jpsisAds.get({
    placement,
    count: 1,                          // até 3
    payToken: req.session.payToken,    // opcional: personaliza (veja Segmentação)
    userKey: req.session.userId,       // opcional: chave do cache por usuário
  });
  res.json(list);
});

O get() nunca lança erro: se o hub estiver fora do ar ou demorar mais de 2,5 s, devolve lista vazia e o sistema segue normalmente. O resultado fica em cache pelo tempo que o hub indicar (cache_ttl, hoje 5 minutos).

<div id="anuncio-topo"></div>
<script src="/static/jpsis-ads-widget.js"></script>
<script>
  JpsisAds.render("#anuncio-topo", {
    endpoint: "/api/anuncios?placement=banner",
    placement: "banner",
    theme: "auto", // "auto" segue o sistema operacional; "light" ou "dark" para combinar com o seu sistema
  });
</script>

Quando não há anúncio, o elemento some e não ocupa espaço. Os links abrem em nova aba com rel="noopener sponsored", e cada anúncio leva o selo Anúncio.

Desenhando você mesmo

Se preferir montar o visual no seu sistema, use os campos do anúncio e siga duas regras:

  1. carregue o view_url uma vez, quando o anúncio aparecer na tela (por exemplo, com uma <img> invisível);
  2. use o click_url como link, sem trocar pelo destino final, senão o clique não é contado.

Endpoint

POST https://jpsis.com.br/api/ads/v1/serve — corpo JSON (ou form-urlencoded) com a autenticação do sistema, a mesma da API de micro-transações:

Campo Obrigatório Descrição
client_id, client_assertion_type, client_assertion sim Certificado da licença (o SDK preenche)
placement não banner (padrão), card ou text
count não De 1 a 3 anúncios (padrão 1)
pay_token ou access_token não Token do usuário, para personalizar. Se for inválido, é ignorado e a resposta vem sem personalização.

Resposta:

{
  "object": "list",
  "placement": "banner",
  "data": [
    {
      "id": "ad_mi0f8k2…",
      "object": "ad",
      "title": "Conheça o RadioBox",
      "body": "Monitore seus rádios e enlaces com alertas em tempo real.",
      "image_url": "https://jpsis.com.br/files/…",
      "cta_label": "Saiba mais",
      "click_url": "https://jpsis.com.br/api/ads/c/eyJh…",
      "view_url": "https://jpsis.com.br/api/ads/v/eyJh…"
    }
  ],
  "cache_ttl": 300,
  "personalized": true
}

data pode vir vazio: não há anúncio para aquele sistema e formato no momento.

Erros

O formato é o mesmo da API de pagamentos: { "error": "<código>", "error_description": "<mensagem>" }.

HTTP error Quando acontece
400 invalid_placement Formato diferente de banner, card ou text
401 invalid_client client_assertion ausente, inválida ou repetida
403 license_inactive Licença suspensa, revogada ou vencida

Medição

No painel (Anúncios) aparecem, por anúncio e por dia em cada sistema:

  • Visualizações — o anúncio ficou pelo menos 50% visível na tela;
  • Cliques — o usuário clicou no anúncio;
  • CTR — cliques ÷ visualizações.

Os links de rastreio são assinados (HMAC) e valem 7 dias. O destino do clique é sempre o cadastrado no painel, nunca um endereço vindo do link, então ninguém consegue usar o rastreio para redirecionar para outro site. Não guardamos dados pessoais nas estatísticas: só contadores por anúncio, dia e sistema.

Testando

Com o hub rodando localmente e um banco de testes:

pnpm tsx --env-file=.env scripts/test-ads-api.mts

O script verifica, contra a API de verdade:

  • entrega por formato e segmentação por sistema;
  • que um produto nunca é anunciado dentro de si mesmo;
  • a ocultação de produtos que o usuário já tem;
  • os períodos de início e fim;
  • a contagem de visualização e clique, e o redirecionamento seguro;
  • a recusa de tokens adulterados e de assinatura forjada.

Não rode o script contra produção.