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

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/.
  • 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

  1. Escrever o jpsis-product.json e validar com pnpm validate:product.
  2. Importar no painel (Admin → Produtos → Importar arquivo do produto).
  3. Publicar a primeira versão (artefatos) e cadastrar a imagem de software.
  4. Implementar o login SSO com jpsis-client.ts.
  5. Aplicar os limites de config, tratando -1 como ilimitado.
  6. Testar com uma licença de teste: login, limites, add-on e suspensão.
  7. Escrever o manual na central de ajuda.
  8. Opcional: pagamentos dentro do sistema e anúncios.
  9. 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.

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:

  • -1 significa 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, pelo name;
  • 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:

  1. No seu computador: node deploy/publish-artifacts.mjs --source <pasta do sistema>. O script envia as imagens Docker, o docker-compose.yml e o manifest.json para o bucket privado.
  2. 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.
  3. 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 (o sub do 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, no id_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 com checkLicense().

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:product sem erros, e o arquivo versionado no repositório do sistema.
  • Imagem de software cadastrada e marcada como atual.
  • Login SSO funcionando com uma conta MEMBER e outra OWNER.
  • Todos os limites do configSchema aplicados 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.