마켓플레이스 애플리케이션 개발 가이드

Blesium 앱은 Shopify App Store 또는 Slack 앱과 같이 대시보드 및 제품(CRM, ERP, 전자 상거래, 메일 등)에 새로운 기능을 추가하는 추가 기능입니다. 휴대폰에 설치된 모바일 애플리케이션이 아닙니다.

작동 모델

애플리케이션은 "원격 HTTP" 모델에서 실행됩니다. 코드는 Blesium에 로드되지 않으며, 서버의 네트워크 경계를 넘어서 실행되며 서명된 SSRF 보호 속도 제한 REST 호출을 통해 통신합니다. 데이터베이스에 직접 액세스할 수 없습니다.

• 블레시움에서 → 애플리케이션의 ID, 카테고리, 대상 제품, 요청된 권한, 가격 및 버전 기록
• 네가 한 명 있잖아 → 응용 프로그램 자체: 비즈니스 논리, 인터페이스, 데이터 처리
• 데이터 액세스 → API를 통해서만, 테넌트가 승인한 권한 내에서만

1. 귀하의 어플리케이션 정의

콘솔에서 새 애플리케이션을 만들 때 작성해야 하는 필드:

• 메시지 → 매장에 표시된 이름
• 슬러그 → 주소 첨부; 소문자, 숫자 및 하이픈만
• 범주 → 다음의 표준 목록 중 하나
• 설명 → 응용 프로그램이 수행하는 작업
• 대상 제품 → crm · erp · b2b · 메일 · 콜센터 · 상점 · musavir
• 필요한 권한 → 애플리케이션이 작동해야 하는 범위
• 가격 → 무료 · 일회용 · 구독

범주는 반드시 표준 목록에서 나와야 합니다. 목록 밖의 키는 제출을 거부합니다.

• 통합 → 외부 시스템에 Blesium을 연결합니다
• 보고서 → 대시보드에 보고서/지표를 추가합니다
• 테마 → 비주얼 테마
• 자동화 → 워크플로우 자동화
• 판매 채널 → 판매 채널
• 메시지 채널 → 메시징 채널
• 배송 → 화물/배송
• 위젯 → 위젯 패널
• 섹터_팩 → 섹터 패키지
• 언어_팩 → 언어 패키지
• 기타 → 기타

2. 권한

애플리케이션은 설치 중에 요청하고 테넌트가 승인한 권한으로만 실행됩니다. 권한을 적게 요청하세요: 불필요하게 넓은 권한은 설치 승인에 대한 신뢰를 잃게 됩니다.

3. 인증

Blesium API에 대한 각 요청은 API 키로 서명됩니다. 키 포맷은 blsk_{ortam}_{kimlik}_{gizli}이며, 비밀 부분은 생성 시에 한 번만 표시된다.

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

4. 웹훅으로 이벤트를 감시

끊임없이 질문을 하는 대신에, 그것이 일어날 때 연락을. 각 배달은 세 개의 제목이 함께 제공됩니다.

• 블레이드 이벤트의 이름(또는. 청구서.지불)
• 블레쿰 → 배송 ID; 중복 제거에 사용
• 블레쿰 → 원시 본문의 HMAC-SHA256 서명 (십육진법)

구독할 수 있는 이벤트와 트리거되는 시기:

• 메시지를 보내기 → 새 청구서 생성
• 청구서. 지불 → 청구서 지불
• 청구서. 환불 → 청구서 반환
• 구독 갱신 → 구독 갱신
• 2016년 1월 1일 변경된 규정 → 구독 플랜 변경
• 취소된 구독 → 구독 취소됨
• 사용자. 초대 → 사용자가 팀에 초대됨
• 사용자가 가입했습니다 → 초대된 사용자가 가입했습니다
• 티켓을 찾을 수 없습니다. → 지원 요청 열림
• 티켓 응답 → 지원 요청 응답

고정 시간 비교를 사용하여 원본 본문과 서명을 비교하여 확인합니다(JSON으로 변환된 경우는 제외 — 공간 차이가 서명을 깨뜨립니다).

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. 릴리스

버전을 게시할 때 입력하는 필드:

• 채널 → 안정판 또는 베타판
• 퍼뜨림 → 0-100%에서 점진적으로 개방
• 상태 → 방송 또는 철회

출판 흐름:

1. 버전 제출 — 버전 번호, 채널 및 변경 내용을 입력합니다.
2. 점진적으로 풀기 — 퍼센트로 확산된 작은 조각에 먼저 릴리스를 제공합니다.
3. 검토 대기 — 앱이 검토를 통과하면 스토어에 출시됩니다.
4. 필요한 경우 복원 — 문제가 있는 버전을 복원합니다. 레코드는 삭제되지 않고 이전 버전으로 복원됩니다.

콘솔에서 애플리케이션 상태를 표시하려면:

6. 릴리스 전 체크리스트

• 필요한 권한을 최소화했습니다.
• 웹훅 서명을 확인하고 반복 전송을 다시 처리하지 않습니다.
• API 키는 서버 측에만 있으며, 누출 백업 스트림이 준비되어 있습니다.
• 응용 프로그램은 실패의 경우 (소프트 드롭) 테넌트의 작업을 중지하지 않습니다.
• 설명과 스크린샷은 응용 프로그램이 실제로 무엇을 하는지 보여줍니다.