Para desenvolvedores
Integrando um sistema ao JPSIS
Este guia mostra como colocar um sistema (SecBox, RadioBox, MikroSDN, MikroERP ou um novo) para ser vendido, instalado, licenciado e acessado pela plataforma JPSIS. Siga na ordem: cada etapa usa a anterior.
O que o JPSIS faz pelo sistema
| O JPSIS cuida de | O sistema cuida de |
|---|---|
| Vitrine, planos, checkout e cobrança recorrente (Stripe) | Descrever seus limites e planos no jpsis-product.json |
| Uma cloud dedicada por cliente (DigitalOcean) | Publicar a imagem e os artefatos de cada versão |
| Licença com certificado digital e verificação periódica | Ler e aplicar os limites da licença |
| Login único com a conta JPSIS (SSO/OIDC) | Botão "Entrar com JPSIS" e mapear os papéis |
| Carteira, micro-transações e anúncios | Usar os SDKs se quiser vender itens avulsos ou exibir anúncios |
| Central de ajuda e tickets | Escrever o manual do produto |
Padrão de integração
Tudo o que o hub lê tem formato fixo e validado. O conteúdo de cada sistema é livre.
- Fixo (padrão JPSIS):
- a estrutura do
jpsis-product.json; - os tipos (
number,boolean,string); - a convenção
-1 = ilimitado; - como os add-ons somam aos limites;
- os endpoints de SSO, licença, pagamentos e anúncios;
- os arquivos em
/etc/jpsis/.
- a estrutura do
- Livre (de cada sistema): quais limites existem (
maxEndpoints,maxCertificates…), os nomes dos planos, os textos de venda e quais add-ons vender.
Assim o hub consegue validar, exibir, cobrar e entregar os limites de qualquer sistema da mesma forma. E nenhum sistema fica preso aos limites de outro.
Checklist
- Escrever o
jpsis-product.jsone validar compnpm validate:product. - Importar no painel (Admin → Produtos → Importar arquivo do produto).
- Publicar a primeira versão (artefatos) e cadastrar a imagem de software.
- Implementar o login SSO com
jpsis-client.ts. - Aplicar os limites de
config, tratando-1como ilimitado. - Testar com uma licença de teste: login, limites, add-on e suspensão.
- Escrever o manual na central de ajuda.
- Opcional: pagamentos dentro do sistema e anúncios.
- Publicar o produto no painel.
Arquivo do produto
O jpsis-product.json descreve o produto para o hub: vitrine, esquema de limites, planos e add-ons. Guarde-o no repositório do sistema, ao lado do código, e versione junto: quando surgir um limite novo no código, ele entra no arquivo no mesmo commit.
- JSON Schema (validação e autocompletar no VS Code):
/desenvolvedores/schema/produto.json. Basta pôr"$schema": "https://jpsis.com.br/desenvolvedores/schema/produto.json"no topo do arquivo. - Exemplo completo:
secbox.jpsis-product.json.
Estrutura
{
"$schema": "https://jpsis.com.br/desenvolvedores/schema/produto.json",
"product": {
"slug": "secbox",
"name": "SecBox",
"tagline": "Cofre de certificados digitais e senhas, com a chave no servidor e tudo em tempo real.",
"kind": "SAAS",
"provisionInstance": true,
"doSize": "s-1vcpu-2gb",
"appUrlTemplate": "https://{host}"
},
"configSchema": [
{ "key": "maxUsers", "label": "Máx. usuários", "type": "number", "default": 5, "help": "Contas ativas no SecBox. -1 = ilimitado." },
{ "key": "maxEndpoints", "label": "Máx. endpoints", "type": "number", "default": 5, "help": "Máquinas com o agente. -1 = ilimitado." }
],
"plans": [
{
"name": "Pro", "price": "349,90", "interval": "MONTH", "highlight": true,
"config": { "maxUsers": 20, "maxEndpoints": 25 },
"features": ["20 usuários", "25 endpoints", "Tempo real em todas as máquinas"]
}
],
"addons": [
{ "name": "+5 usuários", "key": "maxUsers", "amount": 5, "price": "49,90", "interval": "MONTH", "maxQuantity": 20, "description": "Mais 5 contas ativas no SecBox." }
]
}
product
| Campo | Obrigatório | Descrição |
|---|---|---|
slug |
sim | Identificador fixo (a-z, 0-9, -). Vai na URL e no certificado da licença. Não mude depois de publicado. |
name |
sim | Nome na vitrine |
tagline |
não | Frase curta dos cards e do topo da página |
description |
não | Texto da seção "Sobre" |
kind |
não | SAAS (padrão, com cloud) ou SERVICE |
provisionInstance |
não | Criar cloud dedicada por licença (padrão true) |
doRegion / doSize |
não | Região e tamanho do droplet (padrão nyc3 / s-1vcpu-1gb) |
appUrlTemplate |
não | Botão "Abrir sistema". Aceita {host} (domínio próprio do cliente ou IP), {hostname} e {ip} |
configSchema — os limites
Cada item é uma chave que o sistema lê e aplica:
| Campo | Descrição |
|---|---|
key |
camelCase. Use maxAlgo para quantidades e allowAlgo ou hasAlgo para recursos liga/desliga |
label |
Como aparece no painel, na comparação de planos e na Minha área |
type |
number, boolean ou string |
default |
Valor quando o plano não define a chave |
help |
Explica o que conta no limite (ex.: "contas ativas, locais e JPSIS") |
Regras:
-1significa ilimitado. Nunca use outro número negativo.- Quantidade é sempre
number, mesmo que hoje só existam valores pequenos. - Escolha bem a chave. Ela é contrato com o código do sistema: renomear exige mudar o sistema e o arquivo juntos.
- Remover uma chave do arquivo não apaga o valor das licenças antigas. O sistema deve tratar uma chave ausente como o seu
default.
plans
| Campo | Descrição |
|---|---|
name |
Nome do plano. É a chave de atualização: renomear cria um plano novo |
price |
Em reais: "349,90" (texto) ou 349.9 (número) |
interval |
MONTH, YEAR ou ONE_TIME |
highlight |
Marca como "Mais escolhido" |
config |
Valor de cada chave do configSchema. Chave que não existe no esquema é recusada |
features |
Itens do card do plano (texto de venda — não precisam bater com o config) |
addons — ampliar limites
Os add-ons deixam o cliente comprar mais de um limite sem trocar de plano, por exemplo "+5 usuários". O valor entra como item da mesma assinatura do plano, cobrado proporcionalmente ao período.
| Campo | Descrição |
|---|---|
name |
Ex.: "+5 usuários". Chave de atualização |
key |
Chave numérica do configSchema que será ampliada |
amount |
Quanto cada unidade soma |
price |
Preço por unidade, por período |
interval |
MONTH ou YEAR. Só aparece para planos com o mesmo ciclo |
maxQuantity |
Máximo de unidades por licença |
description |
Texto exibido para o cliente |
O limite que o sistema recebe é calculado assim:
default do schema → valor do plano → ajuste manual da licença (admin) → + (amount × unidades) de cada add-on
Um limite -1 continua ilimitado, mesmo com add-ons. O cliente contrata em Minha área → sistema → Ampliar limites, e o admin também pode dar unidades de cortesia na página da licença.
Validar e importar
pnpm validate:product caminho/para/jpsis-product.json
O validador confere a estrutura e a coerência entre esquema, planos e add-ons:
- chave de plano que não existe no esquema (pega erros de digitação como
maxUser); - add-on em chave inexistente ou que não é numérica;
- negativos diferentes de
-1; - add-on sem plano com o mesmo ciclo de cobrança.
Depois, importe em Admin → Produtos → Importar arquivo do produto, enviando o arquivo ou colando o JSON:
- o produto é encontrado pelo
slug; planos e add-ons, peloname; - nada é apagado: itens que não estão no arquivo continuam como estão, e o resumo avisa;
- um produto novo entra como rascunho;
- com a Stripe configurada, os preços são sincronizados na hora;
- na página do produto, Baixar jpsis-product.json exporta o cadastro atual no mesmo formato.
Versões e instalação
Cada cliente recebe uma cloud própria. O hub cria o droplet com a imagem de software atual do produto e instala:
| Arquivo na cloud | Para que serve |
|---|---|
/etc/jpsis/license.json |
Chave da licença, instanceId (o client_id do SSO) e URLs do hub |
/etc/jpsis/license.key |
Chave privada do certificado. Assina as chamadas ao hub e nunca sai da máquina |
/etc/jpsis/license.crt, ca.crt |
Certificado da licença e CA JPSIS |
/etc/jpsis/license-status.json |
Último status da licença, gravado de hora em hora pelo agente jpsis-license |
Publicar uma versão:
- No seu computador:
node deploy/publish-artifacts.mjs --source <pasta do sistema>. O script envia as imagens Docker, odocker-compose.ymle omanifest.jsonpara o bucket privado. - No painel, em Imagens de software:
- cadastre a versão e a pasta dos artefatos;
- cole o script de bootstrap do sistema (modelo em
deploy/cloud-agent/); - marque como imagem atual.
- Clouds novas já sobem com essa versão. As existentes atualizam com
jpsis-deploy fetch <versão>.
Login com a conta JPSIS
O botão Entrar do sistema não pede senha: redireciona ao hub, que confere três coisas — se a pessoa está logada, se a licença daquela cloud está ativa e se ela tem acesso. Use o sdk/jpsis-client.ts, que depende só de jose:
import { JpsisClient } from "./jpsis-client";
const jpsis = new JpsisClient({ redirectUri: "https://<host-do-cliente>/sso/callback" });
app.get("/login", (req, res) => {
const { url, cookie } = jpsis.startLogin();
res.cookie("jpsis_sso", cookie, { httpOnly: true, secure: true, sameSite: "lax", maxAge: 600_000 });
res.redirect(url);
});
app.get("/sso/callback", async (req, res) => {
const r = await jpsis.finishLogin(req.query, req.cookies.jpsis_sso);
// r.user = { id, email, name } r.license = { status, role, plan, config }
req.session.user = { jpsisId: r.user.id, email: r.user.email, name: r.user.name, role: r.license.role };
req.session.limits = r.license.config;
res.redirect("/");
});
Papéis:
| Papel na licença | Sugestão no sistema |
|---|---|
OWNER |
Administrador total (o titular que contratou) |
ADMIN |
Administrador do sistema |
MEMBER |
Usuário comum |
- Use
r.user.id(osubdo token) como identificador fixo da pessoa no sistema, e não o e-mail, que pode mudar. - O titular libera o acesso de outras pessoas em Minha área → sistema → Equipe, até o limite
maxUsers.
Licença e limites
O sistema deve aplicar os limites de config. O hub informa os limites, mas só o sistema sabe contar seus próprios usuários, endpoints e certificados.
Onde ler:
- No login:
r.license.config, noid_token. - No boot e de tempos em tempos:
await jpsis.checkLicense(), ou o arquivo/etc/jpsis/license-status.json, atualizado pelo agente a cada hora. - Sem acesso ao hub: o
license_token(JWT ES256, válido por 72 h) pode ser validado offline pelo JWKS. Assim, quedas curtas do hub não param o cliente.
{
"license_key": "JPS-7Q2KX-…",
"status": "ACTIVE",
"valid": true,
"product": "secbox",
"plan": { "id": "…", "name": "Pro" },
"members": 8,
"config": { "maxUsers": 25, "maxGroups": 15, "maxEndpoints": 25, "maxCertificates": 50, "maxSecrets": 2000 },
"license_token": "eyJ…"
}
No exemplo acima, maxUsers é 25 porque o plano Pro dá 20 e o cliente comprou 1 add-on "+5 usuários". O sistema não precisa saber de add-ons: basta ler config.
Aplicando no código
const UNLIMITED = -1;
/** true se ainda cabe mais um. Chave ausente = usa o default que você definiu no schema. */
export function canAdd(limits: Record<string, unknown>, key: string, current: number, fallback: number) {
const max = typeof limits[key] === "number" ? (limits[key] as number) : fallback;
return max === UNLIMITED || current < max;
}
// ao criar um endpoint:
if (!canAdd(status.config, "maxEndpoints", await countEndpoints(), 5)) {
throw new Error("Limite de endpoints do seu plano atingido. Amplie em jpsis.com.br › Minha área.");
}
Boas práticas:
- Bloqueie só o que é novo. Se o limite cair (troca de plano, fim de add-on), não apague dados: impeça novos cadastros até o cliente voltar ao limite.
- Mostre o uso, por exemplo "18 de 25 usuários", com um link para Minha área → Ampliar limites.
- Licença inválida (
valid: false, por suspensão, revogação ou vencimento): deixe o sistema somente leitura e mostre o motivo. - Recarregue os limites quando o agente atualizar o
license-status.json, para que um add-on comprado valha em até uma hora, ou na hora comcheckLicense().
Pagamentos e anúncios
Os dois usam o mesmo certificado da licença, sem chave de API:
- Micro-transações: cobre recursos avulsos com a carteira JPSIS, dentro da tela do sistema, com pagamento rápido opcional.
- Anúncios: mostre anúncios do ecossistema (banner, card ou texto), com segmentação e medição.
Manual e suporte
- No painel, em Documentação, crie as páginas do produto. Elas aparecem na central de ajuda (
support.jpsis.com.br), com busca. - Os tickets abertos pela Minha área chegam vinculados à licença e à cloud do cliente.
- No sistema, aponte o link "Ajuda" para
https://support.jpsis.com.br/docs/<slug>.
Antes de publicar
-
pnpm validate:productsem erros, e o arquivo versionado no repositório do sistema. - Imagem de software cadastrada e marcada como atual.
- Login SSO funcionando com uma conta
MEMBERe outraOWNER. - Todos os limites do
configSchemaaplicados no código, inclusive-1. - Add-on testado: comprar uma unidade e conferir o novo limite no sistema.
- Licença suspensa no painel deixa o sistema somente leitura.
- Manual com pelo menos a página "Primeiros passos".
- Galeria com capa e produto publicado no painel.