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
- O navegador pede anúncios ao backend do próprio sistema (ex.:
GET /api/anuncios?placement=banner). - 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. - O hub escolhe os anúncios elegíveis para aquele sistema e formato, sorteando pelo peso de cada um.
- 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ó dejose, 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).
Navegador
<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:
- carregue o
view_urluma vez, quando o anúncio aparecer na tela (por exemplo, com uma<img>invisível); - use o
click_urlcomo 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.