POS, OMS 및 ERP 통합
이미 운영 중인 시스템(POS, 주문 관리, ERP)을 SocialHub 로열티 프로그램에 연결하세요. 관리형 커넥터를 구성하여 SAP, Dynamics 365, Manhattan Active Omni, IBM Sterling 또는 Salesforce 앱 내에서 사용할 수 있습니다. 또는 동일한 관리형 v2 REST API를 통해 다른 시스템을 통합할 수도 있습니다. 테넌트 키로 인증되고, 엔드포인트별로 범위가 지정되며, 모든 호출에 대한 감사가 수행됩니다.
1개의 API, 3개의 시스템 유형
아래의 모든 통합은 Authorization: Bearer fl_live_… 테넌트 키를 사용하는 HTTPS 기반 v2 REST API 방식입니다. 대조 작업에는 읽기 전용 키를 사용하고, 포인트를 지급하거나 쿠폰을 사용할 때만 쓰기 범위 키를 사용하십시오. 전자상거래 플랫폼(Shopify, Amazon, TikTok Shop)의 경우 기본 채널 커넥터를 사용하는 것이 좋습니다. 이 가이드는 기본 채널 커넥터가 없는 시스템을 위한 것입니다.
관리형 커넥터
5개의 엔터프라이즈 시스템의 경우 통합 코드를 전혀 작성할 필요가 없습니다. 데이터 및 통합에서 연결(엔드포인트 + 암호화된 자격 증명)을 구성하고, 검증한 후 모의 실행을 하면 됩니다. 각 커넥터는 공급업체의 주문, 고객 및 제품 데이터를 표준화하여 아래에 설명된 동일한 API를 통해 전달합니다. 즉, 동일한 범위, 동일한 멱등성, 동일한 관리 파이프라인을 사용합니다. 각 커넥터에는 검증 단계가 표시되어 있습니다.
Salesforce — CRM/OMS
테스트 데이터로 검증됨주문/반품/계정 연락처/제품2 ( REST + SOQL 사용) 클라이언트 자격 증명 OAuth.
SAP S/4HANA — ERP
테스트 데이터로 검증됨OData A2X 서비스를 통한 판매 주문/비즈니스 파트너/제품 마스터; BTP OAuth.
Dynamics 365 — ERP / CRM
테스트 데이터로 검증됨Dataverse(CE)가 검증되었습니다. 재무 및 운영이 발판을 마련했습니다. 엔트라아이디 OAuth.
맨해튼 액티브 옴니 — OMS
디자인 파트너 검증에서주문/반품/고객; 테넌트의 인터페이스 매핑 문서에 따라 매핑이 완료됩니다.
IBM 스털링 — OMS
디자인 파트너 검증에서getOrderList / REST API 봉투를 통해 반환합니다. 파이프라인에 구성된 상태 코드.
테스트 데이터로 검증됨: 공급업체가 공개한 API를 기준으로 매핑을 구축하고 검증했으며, 최초 배포 시 실제 환경에서 검증하고 확인합니다. 설계 파트너 검증 중: 온보딩 과정에서 해당 테넌트의 통합 문서를 기준으로 매핑을 확정합니다. 여기에 없는 시스템은 아래 API를 통해 직접 통합합니다.
고객 데이터 및 마케팅 강화
주문 캡처와 별도의 기능: 고객 프로필이 이미 존재하는 플랫폼을 연결하고 Flash는 수신자별 특성(이름, 라이프사이클 단계, 사용자 정의 속성)으로 전송 시 각 이메일을 강화합니다. 이메일을 통한 읽기 전용 조회이므로 회원을 생성하거나 PII를 노출하지 않습니다. 데이터 및 통합에서 연결을 구성하면 각 연결을 저장하는 순간 실시간 자격 증명을 기준으로 상태를 확인합니다.
CDP
Salesforce 데이터 클라우드 · 세그먼트 · Adobe 경험 플랫폼
CRM
HubSpot · Microsoft Dynamics 365
마케팅
Braze · Klaviyo · 반복 가능
인증 방식은 각 벤더마다 다릅니다. API 키, 개인 키 또는 OAuth2 클라이언트 자격 증명을 사용할 수 있습니다(OAuth의 경우 Flash는 실행될 때마다 새로운 액세스 토큰을 가져오므로 장기 유효 기간의 베어러 토큰은 저장되지 않습니다). 자격 증명은 저장 시 암호화되며 다시는 노출되지 않습니다.
POS(판매 시점 관리) 시스템 통합
계산대는 단 한 번의 호출로 구매를 로열티 가치로 전환합니다. 판매를 주문으로 등록하면 SocialHub가 회원 정보를 처리합니다(귀하가 생성). externalId이메일 또는 memberId해당 프로그램의 적립 규칙에 따라 포인트를 지급합니다. 필요할 때 회원 키를 사용하여 회원을 조회하거나 생성할 수 있습니다.
판매 보상 (주문 후)
// One call: post the sale as an order. SocialHub resolves the member, applies the
// program's earn rules (tier multiplier + daily cap) and records the order — you
// don't compute points. The member is resolved by memberId > externalId > email.
POST https://flash.socialhub.ai/api/v2/orders
Authorization: Bearer fl_live_…
Idempotency-Key: pos-90871 // safe retries — one sale never awards twice
Content-Type: application/json
{
"externalOrderId": "90871",
"customer": { "externalId": "POS-CUST-5512" }, // or { "email": "…" } / { "memberId": "…" }
"totalAmount": 120.00,
"storeId": "st_…"
}
// → 200 { "data": { "awarded": 6, "balance": 1820, "memberId": "mem_…" } }
// Not a member yet → { "awarded": 0, "reason": "not-a-member" } (never auto-created).구성원 찾기 또는 만들기
// Look up a member by your own key or email (exact match), or create one:
GET https://flash.socialhub.ai/api/v2/members?externalId=POS-CUST-5512 // or ?email=ada@acme.com
// → 200 { "data": [ { "id": "mem_…", "externalId": "POS-CUST-5512", … } ], "total": 1 }
POST https://flash.socialhub.ai/api/v2/members // create/upsert (marketing consent stays OFF)
{ "email": "ada@acme.com", "fullName": "Ada Lovelace", "externalId": "POS-CUST-5512" }
// → 201 created / 200 existing (idempotent on externalId)계산대에서 쿠폰을 사용하세요
// Cashier scans the member's coupon code → mark it redeemed at the register.
POST https://flash.socialhub.ai/api/v2/coupons/{couponId}/redeem
Authorization: Bearer fl_live_…
// → 200 redeemed
// → 404 coupon not found / already redeemed (treat as "do not honor")GET /members/{id}/points, /tier 및 /coupons 명령어를 사용하여 회원의 잔액, 등급 및 쿠폰 정보를 읽어 계산대에서 보여주세요.
주문 관리 통합
기본 커넥터(Shopify, Amazon, TikTok Shop)가 있는 전자 상거래 플랫폼의 경우 이 커넥터를 켜면 작업이 완료됩니다. 다른 주문 관리 시스템의 경우 주문 이벤트를 주문 API에 게시하세요. 프로그램 규칙에 따라 자동 보상을 수집하고 그에 비례하여 클로 포인트를 환불해 드립니다. OMS가 호출을 유도합니다(인바운드 웹훅이 필요하지 않음).
주문 적립; 다시 발톱으로 환불
// On Shopify / Amazon / TikTok Shop? Use the NATIVE channel connectors (Settings →
// Channels). For any OTHER OMS, your system calls these on its own order events.
//
// order paid / fulfilled → ingest (auto-awards by the program's earn rules):
POST https://flash.socialhub.ai/api/v2/orders
Idempotency-Key: SO-44821
{ "externalOrderId": "SO-44821", "customer": { "email": "ada@acme.com" }, "totalAmount": 240.00 }
// → 200 { "data": { "awarded": 12, "memberId": "mem_…" } }
// Same id + a DIFFERENT amount → 409 ORDER_CONFLICT (orders are immutable).
// order returned / refunded → proportional points claw-back, idempotent per refund:
POST https://flash.socialhub.ai/api/v2/orders/SO-44821/refund
{ "refundId": "re_1", "reason": "returned 1 item", "amount": 80.00 } // omit amount = full
// → 200 { "data": { "clawedBack": 4, "balance": 1816 } }
// Backfill / bulk: POST /orders/batch (≤100, 207 Multi-Status, per-item results).아직 회원이 아니신가요? 수집 반환 보상: 0 / reason:not-a-member(자동 생성되지 않음). POST를 사용하여 등록하세요. /members 먼저, 주문을 통해 수익을 얻고 싶을 때입니다.
ERP 및 마스터 데이터 통합
양방향으로 기록 시스템에 맞춰 충성도를 유지하세요. 스토어와 회원 마스터를 푸시한 다음(externalId에 의한 멱등성 upsert) ?updatedSince=를 사용하여 점진적으로 조정하므로 각 동기화에서 변경된 내용만 가져옵니다.
가게 주인을 밀어
// Push your store master to SocialHub (upsert by your ERP store code):
POST https://flash.socialhub.ai/api/v2/stores
{ "name": "Downtown Flagship", "externalId": "ERP-STORE-018", "city": "New York" }
// → 201 created / 200 updated (idempotent on externalId)
// PUT /api/v2/stores/{id} updates a known store. GET to reconcile / pull ids.회원 푸시 및 점진적인 조정
// Push the member master (idempotent upsert by your externalId; consent OFF unless
// you explicitly opt in). Nightly full re-push is safe — existing members update.
POST https://flash.socialhub.ai/api/v2/members/batch // ≤100 per call, 207 Multi-Status
{ "members": [ { "email": "ada@acme.com", "fullName": "Ada Lovelace", "externalId": "ERP-7741" } ] }
// Incremental reconcile — only what changed since your last sync:
GET https://flash.socialhub.ai/api/v2/members?updatedSince=2026-06-26T00:00:00Z&limit=200
GET https://flash.socialhub.ai/api/v2/orders?updatedSince=2026-06-26T00:00:00Z // orders too
// For governed business metrics (GMV, redemption, active members) into BI, query the
// semantic layer over MCP (metrics:read) instead of aggregating raw rows yourself.제품 카탈로그를 푸시하세요(PIM)
// Push your product catalog (idempotent upsert by your own external_id). One
// endpoint takes brands, categories, products, variants and inventory together.
POST https://flash.socialhub.ai/api/v2/catalog/import
{ "source": "erp",
"brands": [ { "externalId": "B-AURELIA", "name": "Aurelia" } ],
"categories": [ { "externalId": "C-RINGS", "name": "Rings" } ],
"products": [ { "externalId": "P-9001", "title": "Solitaire Ring",
"brandExternalId": "B-AURELIA", "categoryExternalId": "C-RINGS",
"descriptionHtml": "<p>18k…</p>",
"content": [ { "externalId": "P-9001-spec", "contentType": "spec",
"body": "1.0ct, 18k white gold, GIA" } ] } ],
"variants": [ { "externalId": "V-9001-7", "productExternalId": "P-9001",
"sku": "AUR-RING-7", "price": 4200 } ],
"inventory": [ { "variantSku": "AUR-RING-7", "locationRef": "WH-1", "available": 12 } ] }
// → 200 with per-entity {inserted,updated} + errors[] (a bad row never aborts the batch).
// On Shopify? Products map in automatically — images + rich descriptions included.
// Read back: GET /api/v2/products · /products/{id} · /categories · /brands일괄 처리량은 호출당 100개 이하(항목별 다중 상태 결과 207개)입니다. 키별 처리량 제한을 준수하고 사용량이 적은 시간대에 전체 재동기화를 실행하십시오. 카탈로그 가져오기는 외부 저장소에서 관리되며, SocialHub는 제품 정보를 ERP 시스템에 다시 기록하지 않습니다.
권한, 범위 및 보안
테넌트 범위 키
모든 통화에는 하나의 팀에 연결된 fl_live_ 키가 포함됩니다. 키는 테넌트 간에 공유되지 않습니다. 통합별로 별도의 키를 생성하여 다른 키를 건드리지 않고도 하나의 키를 변경할 수 있습니다.
읽기/쓰기 사전 설정
정산 작업에는 읽기 전용 키가 사용됩니다. 포인트 적립 또는 쿠폰 사용이 이루어지는 POS/OMS 경로에만 쓰기 권한을 부여하십시오. 시스템별로 최소 권한 원칙을 적용해야 합니다.
멱등성 키
쓰기 작업 시 Idempotency-Key 헤더를 전송합니다(주문에는 자체 externalOrderId도 포함됩니다). 재시도 시 원래 결과가 재생됩니다. 페이로드가 다른 동일한 키는 거부됩니다. 즉, 한 번의 판매로 두 번 보상이 지급되지 않습니다.
기본적으로 감사됨
모든 API 호출은 기록되어 API 키 → 최근 활동에서 확인할 수 있으므로 통합의 쓰기 작업은 항상 키와 연결하여 추적할 수 있습니다.
전체 엔드포인트 참조: REST API · 빠른 시작 · MCP (BI로 메트릭 전송)