Handleiding voor de ontwikkeling van Marketplace-toepassingen

Blesium-apps zijn add-ons die nieuwe mogelijkheden toevoegen aan dashboards en producten (CRM, ERP, e-commerce, mail, enz.) — zoals Shopify App Store- of Slack-apps. Niet mobiele applicaties geïnstalleerd op de telefoon.

Werkmodel

Uw applicatie draait op het "remote HTTP" model: code wordt niet geladen in Blesium, het draait buiten de netwerkgrens op uw server en communiceert met ondertekende, SSRF beschermde, snelheidsbeperkte REST-oproepen. Geen directe toegang tot de database.

• Bij het Blesium. → De identiteit van de applicatie, categorie, doelproducten, gevraagde machtigingen, prijzen en versiegeschiedenis
• Je hebt er een. → De applicatie zelf: bedrijfslogica, interface, gegevensverwerking
• Toegang tot gegevens → Alleen via API, alleen binnen de door de tenant goedgekeurde machtigingen

1. Definieer uw toepassing

Velden die moeten worden ingevuld bij het maken van een nieuwe toepassing vanuit de console:

• Naam → Naam weergegeven in de winkel
• Slak → Adresbijlage; alleen kleine letters, cijfers en koppeltekens
• Categorie → Een van de volgende canonieke lijsten
• Beschrijving → Wat de applicatie doet
• Doelproducten → crm · erp · b2b · mail · call center · winkel · musavir
• Vereiste rechten → Scopes die uw applicatie nodig heeft om te werken
• Prijzen → Gratis · Eenmalig · Abonnement

De categorie moet uit de canonieke lijst komen; een sleutel buiten de lijst zal de inzending weigeren.

• integratie → Verbindt Blesium met een extern systeem
• verslag → Voegt rapport/indicator toe aan dashboard
• thema → Visueel thema
• automatisering → Werkstroomautomatisering
• Verkoopkanaal → Verkoopkanaal
• messaging_kanaal → Berichtenkanaal
• Verzending → Cargo/vervoer
• widget → Widgetpaneel
• sector_pack → Sectorpakket
• Taalpakket → Taalpakket
• overige → andere

2. Machtigingen

Uw applicatie wordt alleen uitgevoerd met de machtigingen die het vraagt en de tenant goedkeurt tijdens de installatie. Vraag om minder rechten: onnodig brede rechten verliezen het vertrouwen in installatieautorisatie.

3. Authenticatie

Elke aanvraag naar de Blesium API wordt ondertekend met een API-sleutel. Het sleutelformaat is blsk_{ortam}_{kimlik}_{gizli}, en het geheime deel wordt slechts eenmaal getoond op het moment van aanmaken.

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

4. Luisteren naar gebeurtenissen met webhooks

In plaats van constant vragen te stellen, neem contact op wanneer het gebeurt. Elke levering wordt geleverd met drie koppen:

• x-blesyum-event De naam van het evenement (of. (invoice.paid)
• x-blesyumlevering → Leverings-ID; gebruik om duplicaten te elimineren
• x-blesyum-handtekening → HMAC-SHA256 handtekening van ruwe body (hex)

Gebeurtenissen waarop u zich kunt abonneren en wanneer ze worden geactiveerd:

• factuur.created → Nieuwe factuur aangemaakt
• factuur.betaald → Factuur betaald
• factuur.herfinancierd → Factuur geretourneerd
• abonnement.vernieuwd → Abonnement verlengd
• Abonnement.plan_changed → Abonnementsplan gewijzigd
• Abonnement. → Abonnement geannuleerd
• Gebruiker.invited → Gebruiker uitgenodigd voor team
• Gebruiker.geregistreerd → Uitgenodigde gebruiker is lid geworden
• Ticket.nl → Support aanvraag geopend
• Ticket.beantwoord → Ondersteuningsverzoek beantwoord

Verifieer de handtekening tegen de ruwe body, met behulp van een vergelijking met vaste tijd (niet zoals geconverteerd naar JSON — verschillen in ruimte zullen de handtekening breken):

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. Loslaten

Velden die u invoert bij het publiceren van een versie:

• Kanaal → stabiel of bèta
• Verspreiden → Geleidelijke opening van 0–100%
• Status → Uitgezonden of ingetrokken

Publicatiestroom:

1. Versie indienen — Voer het versienummer, kanaal en wijzigingsnotitie in.
2. Pak geleidelijk uit — Geef eerst een kleine hoeveelheid vrij met een spreidingspercentage.
3. Wacht op beoordeling: wanneer de app is goedgekeurd voor beoordeling, wordt deze vrijgegeven in de store.
4. Terugdraaien indien nodig — Herstel de probleemversie; de record wordt niet verwijderd, de vorige versie wordt hersteld.

De status van uw toepassing weergeven in de console:

6. Checklist voor pre-release

• U hebt de vereiste machtigingen geminimaliseerd.
• U valideert de webhook handtekening, u verwerkt de herhaalde levering niet opnieuw.
• De API-sleutel bevindt zich alleen aan de serverzijde; uw lek-backupstream is klaar.
• Uw applicatie stopt het werk van de huurder niet in geval van een storing (soft drop).
• De beschrijving en screenshots laten zien wat de app eigenlijk doet.