Diffsome Documentation
Diffsome is an all-in-one Headless Backend Platform for CMS, E-commerce, Community, and Reservation. Build any frontend with our TypeScript SDK or REST API.
Blog & CMS
Markdown, categories, tags
E-commerce
Products, Cart, Orders, Payments
Community
Boards, Posts, Comments
Reservation
Services, Staff, Time Slots
Why Diffsome?
- Headless Architecture - Use any frontend: React, Vue, Next.js, Nuxt, Flutter, or native apps
- Multi-tenant - One account, unlimited sites with isolated data
- TypeScript SDK - Type-safe API calls with full IntelliSense
- Built-in Payments - Toss Payments (Korea) & Stripe (Global) integrated
Quick Start
1 Create Account & Get API Key
Sign up at Dashboard, create a tenant (site), and get your API Key from Settings.
2 Install SDK
npm install @diffsome/sdk
3 Initialize Client
import { Diffsome } from '@diffsome/sdk'
const client = new Diffsome({
baseUrl: 'https://www.diffsome.com',
tenantId: 'your-tenant-id',
apiKey: 'pky_xxxxxxxxxxxxxxxx',
persistToken: true, // Auto-save auth token
})
4 Make API Calls
// Get blog posts
const { data: posts } = await client.blog.list()
// Get products
const { data: products } = await client.shop.listProducts()
// User login
const { token, member } = await client.auth.login({
email: '[email protected]',
password: 'password'
})
Authentication
Diffsome uses Bearer token authentication for protected endpoints. Members can register, login, and manage their sessions.
Endpoints
/auth/registerRegister new member/auth/loginLogin & get token/auth/logoutLogout (invalidate token)/auth/meGet current member info/auth/forgot-passwordRequest password reset/auth/reset-passwordReset password with token/auth/find-emailFind email by criteria/profileGet member profile/profileUpdate member profileSocial Login
/auth/social/providersList enabled providers/auth/social/{provider}Get OAuth redirect URL/auth/social/{provider}/tokenExchange token (mobile)/auth/social/{provider}/connectLink social account/auth/social/disconnectUnlink social accountSDK Example
// Register
const { member, token } = await client.auth.register({
email: '[email protected]',
password: 'password123',
name: 'John Doe'
})
// Login
const { member, token } = await client.auth.login({
email: '[email protected]',
password: 'password123'
})
// Get current user (requires auth)
const member = await client.auth.me()
Multi-tenancy
Diffsome is a multi-tenant platform. Each tenant (site) has completely isolated data - members, products, orders, content, etc.
How it works
- Tenant ID - Unique identifier for each site (e.g.,
my-shop) - Data Isolation - Each tenant's data is completely separate
- API Key - Each tenant has its own API key for authentication
- Custom Domain - Optional custom domain support
API URL Pattern
Examples
// Tenant: my-shop
GET https://www.diffsome.com/api/my-shop/products
GET https://www.diffsome.com/api/my-shop/blog
POST https://www.diffsome.com/api/my-shop/auth/login
// Tenant: another-site
GET https://www.diffsome.com/api/another-site/products
GET https://www.diffsome.com/api/another-site/blog
API Structure
All API endpoints follow this base URL pattern:
Request Headers
// For public endpoints (optional)
X-API-Key: pky_xxxxxxxxxxxxxxxx
// For protected endpoints (required)
Authorization: Bearer {member_token}
Content-Type: application/json
Response Format
// List response
{
"data": [...],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 15,
"total": 75
}
}
// Single resource
{
"data": { ... }
}
Error Handling
All API errors return a consistent JSON format with appropriate HTTP status codes.
Error Response Format
{
"message": "The given data was invalid.",
"errors": {
"email": ["The email field is required."]
}
}
HTTP Status Codes
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid token |
| 403 | Forbidden - No permission |
| 404 | Not Found |
| 422 | Validation Error |
| 500 | Server Error |
Site Info
Get tenant site information, currency settings, and formatting helpers. These are public endpoints - no API key required.
Endpoints
/siteGet site info (name, description, settings)/site/currencyGet currency settingsSDK Example
// Get site info
const info = await client.site.getInfo()
// Get currency settings
const currency = await client.site.getCurrency()
// Format price
const formatted = client.site.formatPrice(50000) // "₩50,000"
Blog
Markdown-based blog with categories and tags support.
Endpoints
/blogList posts/blog/{slug}Get post by slug/blog/categoriesList categories/blog/tagsList tagsQuery Parameters
| category | Filter by category slug |
| tag | Filter by tag slug |
| search | Search in title and content |
| per_page | Items per page (default: 15) |
| page | Page number |
SDK Example
// List posts
const { data, meta } = await client.blog.list({
category: 'tech',
per_page: 10
})
// Get single post
const post = await client.blog.get('my-post-slug')
// Get categories
const categories = await client.blog.categories()
Board
Community boards with posts. Supports multiple board types (notice, free, QnA, etc.).
Endpoints
/boardsList boards/boards/{board}Get board info/boards/{board}/postsList posts in board/postsCreate post (auth required)/posts/{post}Get post detail/posts/{post}Update post/posts/{post}Delete postSDK Example
// List boards
const boards = await client.boards.list()
// Get posts from a board
const { data, meta } = await client.boards.posts('free')
// Create post (requires auth)
const post = await client.boards.createPost({
board_id: 1,
title: 'Hello World',
content: 'Post content here...'
})
Media
Upload and manage media files (images, documents, etc.).
Endpoints
/mediaList media files/mediaUpload file (multipart)/media/{media}Delete fileSDK Example
// Upload file
const media = await client.media.upload(file, {
folder: 'posts'
})
// List media
const { data } = await client.media.list()
Products
E-commerce product catalog with categories, variants, and reviews.
Endpoints
/productsList products/products/{slug}Get product detail/products/{slug}/relatedRelated products/products/{slug}/bundle-itemsBundle items/categoriesList categories/categories/{slug}Category detailQuery Parameters
| category | Filter by category slug |
| search | Search in name/description |
| min_price | Minimum price filter |
| max_price | Maximum price filter |
| is_featured | Featured products only |
| in_stock | In-stock products only |
| type | Product type (simple, digital, subscription, bundle) |
SDK Example
// List products with filters
const { data, meta } = await client.shop.listProducts({
category: 'electronics',
min_price: 100,
max_price: 500,
in_stock: true
})
// Get product detail
const product = await client.shop.getProduct('iphone-15')
// Get featured products
const featured = await client.shop.featuredProducts(8)
Cart
Shopping cart management. Works with both authenticated members and guest sessions.
Endpoints
/cartGet cart/cart/itemsAdd item to cart/cart/items/{item}Update item quantity/cart/items/{item}Remove item/cartClear cart/cart/mergeMerge guest cart on login/cart/validateValidate cart before checkoutSDK Example
// Get cart
const cart = await client.shop.getCart()
// Add item
const cart = await client.shop.addToCart({
product_id: 123,
quantity: 2,
variant_id: 456 // optional
})
// Update quantity
await client.shop.updateCartItem(itemId, { quantity: 3 })
// Remove item
await client.shop.removeFromCart(itemId)
Orders
Order creation and management. Requires authentication.
Endpoints
/ordersList my orders/ordersCreate order from cart/orders/previewPreview order (calculate totals)/orders/{order_number}Get order detail/orders/{order_number}/cancelCancel order/orders/{order_number}/downloadsDigital downloadsSDK Example
// Create order
const order = await client.shop.createOrder({
shipping_address: {
name: 'John Doe',
phone: '010-1234-5678',
address: '123 Main St',
city: 'Seoul',
zip: '12345'
},
coupon_code: 'SAVE10' // optional
})
// List orders
const { data } = await client.shop.listOrders()
Wishlist
Save products for later. Requires authentication.
Endpoints
/wishlistGet wishlist/wishlistAdd to wishlist/wishlist/toggleToggle wishlist/wishlist/checkCheck if in wishlist/wishlist/check-bulkBulk check/wishlist/countWishlist count/wishlist/move-to-cartMove items to cart/wishlist/{id}Update wishlist note/wishlist/{id}Remove from wishlist/products/{slug}/wishlist-countProduct wishlist countCoupons
Discount coupons for orders.
Endpoints
/couponsMy available coupons/coupons/validateValidate coupon code/coupons/applyApply coupon to cartSDK Example
// Validate coupon
const result = await client.shop.validateCoupon('SAVE20', 50000)
// Get my coupons
const coupons = await client.shop.myCoupons()
Product Reviews
Product review system. Members can review products they've purchased.
Endpoints
/products/{slug}/reviewsList reviews/products/{slug}/reviews/can-reviewCheck if can review/products/{slug}/reviewsCreate review/reviews/{review}Update review/reviews/{review}Delete review/reviews/{review}/helpfulMark as helpful/my/reviewsMy reviewsDigital Downloads
Download digital products after purchase. Requires authentication.
Endpoints
/my/downloadsMy downloads list/orders/{orderNumber}/downloadsOrder downloads/downloads/{token}Download file/downloads/{token}/infoDownload infoSDK Example
// Get my downloads
const { data } = await client.shop.getMyDownloads()
// Get order downloads
const { data } = await client.shop.getOrderDownloads('ORD-123')
// Get download URL
const { url } = await client.shop.getDownloadUrl('download-token')
Toss Payments
Korean payment gateway integration. Supports card, virtual account, and more.
Endpoints
/payments/statusAvailable payment methods/payments/toss/readyPrepare payment/payments/toss/confirmConfirm payment/payments/toss/cancelCancel/refund payment/payments/toss/virtual-accountCreate virtual accountSDK Example
// Prepare payment
const { clientKey, orderId } = await client.shop.tossPaymentReady({
order_number: 'ORD-123',
success_url: 'https://mysite.com/success',
fail_url: 'https://mysite.com/fail'
})
// Confirm after redirect
const result = await client.shop.tossPaymentConfirm({
payment_key: paymentKey,
order_id: orderId,
amount: 50000
})
Stripe
Global payment gateway. Supports Checkout Session and Payment Intent.
Endpoints
/payments/stripe/checkoutCreate Checkout Session/payments/stripe/intentCreate Payment Intent/payments/stripe/confirmConfirm payment/payments/stripe/verifyVerify after redirect/payments/stripe/refundRefund paymentSDK Example
// Create Checkout Session
const { url } = await client.shop.stripeCheckout({
order_number: 'ORD-123',
success_url: 'https://mysite.com/success',
cancel_url: 'https://mysite.com/cancel'
})
// Redirect to Stripe
window.location.href = url
// Verify after redirect
const result = await client.shop.stripeVerify({
session_id: sessionId
})
Subscriptions
Recurring payments via Stripe. Create and manage subscription plans.
Endpoints
/subscriptionsMy subscriptions/subscriptionsCreate subscription/subscriptions/checkoutCheckout for subscription/subscriptions/setup-intentSetup payment method/subscriptions/verifyVerify checkout/subscriptions/{id}Subscription detail/subscriptions/{id}/cancelCancel subscription/subscriptions/{id}/pausePause subscription/subscriptions/{id}/resumeResume subscriptionReservation
Booking system with services, staff, and time slot management.
Public Endpoints
/reservation/settingsReservation settings/reservation/servicesAvailable services/reservation/staffsAvailable staff/reservation/available-datesAvailable dates/reservation/available-slotsAvailable time slotsProtected Endpoints
/reservationsMy reservations/reservationsCreate reservation/reservations/{number}Reservation detail/reservations/{number}/cancelCancel reservationSDK Example
// Get available slots
const slots = await client.reservation.getAvailableSlots({
service_id: 1,
staff_id: 2,
date: '2024-03-15'
})
// Create reservation
const reservation = await client.reservation.create({
service_id: 1,
staff_id: 2,
date: '2024-03-15',
time: '14:00',
name: 'John Doe',
phone: '010-1234-5678'
})
Reservation Payments
Payment processing for reservations via Toss Payments.
Endpoints
/reservation-payments/toss/readyPrepare reservation payment/reservation-payments/toss/confirmConfirm reservation payment/reservation-payments/{id}/statusPayment statusForms
Dynamic form builder with submissions. Contact forms, surveys, applications, etc.
Endpoints
/formsList forms/forms/{slug}Get form schema/forms/{slug}/submitSubmit form/forms/{slug}/check-ipCheck IP limit/forms/{slug}/submissionsList submissions/my/submissionsMy submissionsSDK Example
// Get form
const form = await client.forms.get('contact')
// Submit form
await client.forms.submit('contact', {
name: 'John Doe',
email: '[email protected]',
message: 'Hello!'
})
Custom Entity
Dynamic data structures. Create custom entities with flexible schemas for any data type.
Entity Endpoints
/entitiesList entities/entitiesCreate entity/entities/{slug}Get entity/entities/{slug}Update entity/entities/{slug}Delete entityRecord Endpoints
/entities/{slug}/recordsList records/entities/{slug}/recordsCreate record/entities/{slug}/records/{id}Get record/entities/{slug}/records/{id}Update record/entities/{slug}/records/{id}Delete recordSDK Example
// Create entity
const entity = await client.entities.create({
name: 'Customers',
slug: 'customers',
schema: {
fields: [
{ name: 'company', type: 'text', required: true },
{ name: 'email', type: 'email' }
]
}
})
// Create record
const record = await client.entities.createRecord('customers', {
company: 'ACME Inc',
email: '[email protected]'
})
Chat - Visitor API
Real-time customer support chat. The visitor API is public and uses a visitor_id cookie for identification.
Endpoints
/chat/conversationsStart conversation/chat/conversationsList my conversations/chat/conversations/{id}Get conversation detail/chat/conversations/{id}/messagesSend message/chat/conversations/{id}/messagesGet messages/chat/conversations/{id}/pollPoll for new messages/chat/conversations/{id}/closeClose conversation/chat/conversations/{id}/typingSend typing indicator/chat/availabilityCheck agent availabilitySDK Example
// Start conversation
const { conversation_id } = await client.chat.start({
visitor_name: 'John',
visitor_email: '[email protected]',
initial_message: 'Hello!'
})
// Real-time connection
const chat = client.chat.connect(conversation_id)
chat.onMessage((msg) => console.log(msg.content))
await chat.send('How can I get a refund?')
// Check availability
const { available } = await client.chat.checkAvailability()
Chat - Agent API
Agent-side chat management. Requires Sanctum authentication.
Endpoints
/chat/agent/conversationsList conversations/chat/agent/conversations/{id}Get conversation/chat/agent/conversations/{id}/messagesSend message/chat/agent/conversations/{id}/assignAssign to agent/chat/agent/conversations/{id}/closeClose conversation/chat/agent/conversations/{id}/reopenReopen conversation/chat/agent/statusUpdate agent status/chat/agent/statsDashboard statsAI Agents
AI-powered agents for automation. Configure, run, and monitor agent executions.
Endpoints
/agentsList available agents/agents/{slug}Get agent detail/agents/{slug}/configureConfigure agent/agents/{slug}/runRun agent/agents/{slug}/executionsList executions/agents/{slug}/statsAgent stats/executions/{executionId}Get execution detailCourses / LMS
Learning management system with courses, lessons, enrollment, and progress tracking.
Public Endpoints
/coursesList courses/courses/{slug}Get course detail/courses/{slug}/enrollEnroll in courseProtected Endpoints
/my/coursesMy enrolled courses/my/courses/{slug}My course progress/my/courses/{slug}/lessons/{id}Get lesson content/my/courses/{slug}/lessons/{id}/completeComplete lesson/my/courses/{slug}/lessons/{id}/progressUpdate progress
Comments
Unified comment system for blog posts, board posts, and standalone pages (guestbook, etc.).
Endpoints
/blog/{slug}/commentsBlog post comments/blog/{slug}/commentsAdd blog comment/posts/{post}/commentsBoard post comments/posts/{post}/commentsAdd board comment/comments/{page_slug}Standalone page comments/comments/{page_slug}Add standalone comment/comments/{id}Update comment/comments/{id}Delete comment/comments/{id}/likeLike/unlike comment