Guia de desenvolvimento de aplicativos Marketplace

Os aplicativos Blesium são complementos que adicionam novos recursos aos painéis e produtos (CRM, ERP, comércio eletrônico, e-mail...) — como os aplicativos da App Store da Shopify ou do Slack. Não aplicativos móveis instalados no telefone.

Modelo de trabalho

Seu aplicativo é executado no modelo "HTTP remoto": o código não é carregado no Blesium, ele é executado além do limite da rede em seu servidor e se comunica com chamadas REST assinadas, protegidas por SSRF e limitadas em velocidade. Não há acesso direto ao banco de dados.

• No Blesium. → A identidade do aplicativo, categoria, produtos de destino, permissões solicitadas, preços e histórico de versões
• Você tem um. → A aplicação em si: lógica de negócios, interface, processamento de dados
• Acesso aos dados → Apenas via API, apenas dentro das permissões aprovadas pelo locatário

1. Defina sua aplicação

Campos a preencher ao criar uma nova aplicação a partir do console:

• Nome → Nome exibido na loja
• Lesma → Anexo de endereço; apenas letras minúsculas, números e hífens
• Categoria → Uma das seguintes listas canônicas
• Descrição → O que faz o aplicativo
• Produtos-alvo → crm · erp · b2b · correio · call center · loja · musavir
• Permissões necessárias → Escopos que seu aplicativo precisa para funcionar
• Preços → Grátis · Único · Assinatura

A categoria deve vir da lista canônica; uma chave fora da lista irá rejeitar o envio.

• integração → Conecta Blesium a um sistema externo
• relatório → Adiciona relatório/indicador ao painel
• tema → Tema visual
• automação → Automação de fluxo de trabalho
• sales_channel → Canal de vendas
• canal_de_mensagens → Canal de mensagens
• Envio → Carga/transporte
• widget → Painel de widgets
• sector_pack → Pacote de setor
• language_pack → Pacote de idiomas
• outros → Outros produtos

2. Permissões

Seu aplicativo será executado apenas com as permissões solicitadas e aprovadas pelo locatário durante a instalação. Peça menos permissões: permissões desnecessariamente amplas perderão a confiança na autorização de instalação.

3. Autenticação

Cada solicitação para a API do Blesium é assinada com uma chave de API. O formato da chave é blsk_{ortam}_{kimlik}_{gizli}, e a parte secreta é mostrada apenas uma vez no momento da criação.

curl https://firmaniz.blescript.com/api/v1/me \
  -H "Authorization: Bearer blsk_live_ab12cd34_gizli-anahtariniz"

4. Ouça eventos com webhooks

Em vez de fazer perguntas constantemente, entre em contato quando isso acontecer. Cada entrega vem com três cabeçalhos:

• x-blesyum-event O nome do evento (ou. fatura.pago)
• x-blesyum-entrega → ID de entrega; use para eliminar duplicatas
• x-blesyum-assinatura → Assinatura HMAC-SHA256 do corpo bruto (hex)

Eventos que você pode assinar e quando eles são acionados:

• fatura.criado → Nova fatura criada
• fatura.pago Fatura paga
• fatura.refinanciado → Fatura devolvida
• assinatura.renovado → Assinatura renovada
• subscription.plan_changed → Plano de assinatura alterado
• subscription.canceled → Assinatura cancelada
• user.invited → Usuário convidado para a equipe
• user.joined → Usuário convidado se juntou
• ticket.criado → Pedido de suporte aberto
• ticket.respondido → Pedido de suporte respondido

Verifique a assinatura contra o corpo bruto, usando uma comparação de tempo fixo (não como convertido para JSON — diferenças de espaço quebrarão a assinatura):

import crypto from "node:crypto";

export function imzaDogrula(rawBody, header, secret) {
  const beklenen = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(beklenen);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

5. Liberação

Campos que você insere ao publicar uma versão:

• Canal → estável ou beta
• Espalhar → Abertura gradual de 0–100%
• Estado → Transmitido ou retirado

Fluxo de publicação:

1. Enviar versão — Insira o número da versão, canal e nota de alteração.
2. Descompacte gradualmente — Dê a liberação para uma pequena fatia primeiro com uma porcentagem de distribuição.
3. Aguarde a revisão: quando o aplicativo passar pela revisão, ele será lançado na loja.
4. Reverter se necessário — Reverte a versão do problema; o registro não é excluído, a versão anterior é restaurada.

Mostrar o status do aplicativo no console:

6. Checklist de pré-lançamento

• Você minimizou as permissões necessárias.
• Você valida a assinatura do webhook, não reprocessa a entrega repetida.
• A chave da API está apenas no lado do servidor; seu fluxo de backup de vazamento está pronto.
• Seu aplicativo não interrompe o trabalho do inquilino em caso de falha (soft drop).
• A descrição e as capturas de tela mostram o que o aplicativo realmente faz.