Diffsome diffsome
Sign up

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

POST/auth/registerRegister new member
POST/auth/loginLogin & get token
POST/auth/logoutLogout (invalidate token)
GET/auth/meGet current member info
POST/auth/forgot-passwordRequest password reset
POST/auth/reset-passwordReset password with token
POST/auth/find-emailFind email by criteria
GET/profileGet member profile
PUT/profileUpdate member profile

Social Login

GET/auth/social/providersList enabled providers
GET/auth/social/{provider}Get OAuth redirect URL
POST/auth/social/{provider}/tokenExchange token (mobile)
POST/auth/social/{provider}/connectLink social account
POST/auth/social/disconnectUnlink social account

SDK 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

https://www.diffsome.com/api/{tenant_id}/{endpoint}

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:

https://www.diffsome.com/api/{tenant_id}/...

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

200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid token
403Forbidden - No permission
404Not Found
422Validation Error
500Server Error

Site Info

Get tenant site information, currency settings, and formatting helpers. These are public endpoints - no API key required.

Endpoints

GET/siteGet site info (name, description, settings)
GET/site/currencyGet currency settings

SDK 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

GET/blogList posts
GET/blog/{slug}Get post by slug
GET/blog/categoriesList categories
GET/blog/tagsList tags

Query Parameters

categoryFilter by category slug
tagFilter by tag slug
searchSearch in title and content
per_pageItems per page (default: 15)
pagePage 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

GET/boardsList boards
GET/boards/{board}Get board info
GET/boards/{board}/postsList posts in board
POST/postsCreate post (auth required)
GET/posts/{post}Get post detail
PUT/posts/{post}Update post
DELETE/posts/{post}Delete post

SDK 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...'
})

Comments

Unified comment system for blog posts, board posts, and standalone pages (guestbook, etc.).

Endpoints

GET/blog/{slug}/commentsBlog post comments
POST/blog/{slug}/commentsAdd blog comment
GET/posts/{post}/commentsBoard post comments
POST/posts/{post}/commentsAdd board comment
GET/comments/{page_slug}Standalone page comments
POST/comments/{page_slug}Add standalone comment
PUT/comments/{id}Update comment
DELETE/comments/{id}Delete comment
POST/comments/{id}/likeLike/unlike comment

Media

Upload and manage media files (images, documents, etc.).

Endpoints

GET/mediaList media files
POST/mediaUpload file (multipart)
DELETE/media/{media}Delete file

SDK 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

GET/productsList products
GET/products/{slug}Get product detail
GET/products/{slug}/relatedRelated products
GET/products/{slug}/bundle-itemsBundle items
GET/categoriesList categories
GET/categories/{slug}Category detail

Query Parameters

categoryFilter by category slug
searchSearch in name/description
min_priceMinimum price filter
max_priceMaximum price filter
is_featuredFeatured products only
in_stockIn-stock products only
typeProduct 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

GET/cartGet cart
POST/cart/itemsAdd item to cart
PUT/cart/items/{item}Update item quantity
DELETE/cart/items/{item}Remove item
DELETE/cartClear cart
POST/cart/mergeMerge guest cart on login
POST/cart/validateValidate cart before checkout

SDK 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

GET/ordersList my orders
POST/ordersCreate order from cart
POST/orders/previewPreview order (calculate totals)
GET/orders/{order_number}Get order detail
POST/orders/{order_number}/cancelCancel order
GET/orders/{order_number}/downloadsDigital downloads

SDK 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

GET/wishlistGet wishlist
POST/wishlistAdd to wishlist
POST/wishlist/toggleToggle wishlist
GET/wishlist/checkCheck if in wishlist
POST/wishlist/check-bulkBulk check
GET/wishlist/countWishlist count
POST/wishlist/move-to-cartMove items to cart
PUT/wishlist/{id}Update wishlist note
DELETE/wishlist/{id}Remove from wishlist
GET/products/{slug}/wishlist-countProduct wishlist count

Coupons

Discount coupons for orders.

Endpoints

GET/couponsMy available coupons
POST/coupons/validateValidate coupon code
POST/coupons/applyApply coupon to cart

SDK 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

GET/products/{slug}/reviewsList reviews
GET/products/{slug}/reviews/can-reviewCheck if can review
POST/products/{slug}/reviewsCreate review
PUT/reviews/{review}Update review
DELETE/reviews/{review}Delete review
POST/reviews/{review}/helpfulMark as helpful
GET/my/reviewsMy reviews

Digital Downloads

Download digital products after purchase. Requires authentication.

Endpoints

GET/my/downloadsMy downloads list
GET/orders/{orderNumber}/downloadsOrder downloads
GET/downloads/{token}Download file
GET/downloads/{token}/infoDownload info

SDK 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

GET/payments/statusAvailable payment methods
POST/payments/toss/readyPrepare payment
POST/payments/toss/confirmConfirm payment
POST/payments/toss/cancelCancel/refund payment
POST/payments/toss/virtual-accountCreate virtual account

SDK 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

POST/payments/stripe/checkoutCreate Checkout Session
POST/payments/stripe/intentCreate Payment Intent
POST/payments/stripe/confirmConfirm payment
POST/payments/stripe/verifyVerify after redirect
POST/payments/stripe/refundRefund payment

SDK 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

GET/subscriptionsMy subscriptions
POST/subscriptionsCreate subscription
POST/subscriptions/checkoutCheckout for subscription
POST/subscriptions/setup-intentSetup payment method
POST/subscriptions/verifyVerify checkout
GET/subscriptions/{id}Subscription detail
POST/subscriptions/{id}/cancelCancel subscription
POST/subscriptions/{id}/pausePause subscription
POST/subscriptions/{id}/resumeResume subscription

Reservation

Booking system with services, staff, and time slot management.

Public Endpoints

GET/reservation/settingsReservation settings
GET/reservation/servicesAvailable services
GET/reservation/staffsAvailable staff
GET/reservation/available-datesAvailable dates
GET/reservation/available-slotsAvailable time slots

Protected Endpoints

GET/reservationsMy reservations
POST/reservationsCreate reservation
GET/reservations/{number}Reservation detail
POST/reservations/{number}/cancelCancel reservation

SDK 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

POST/reservation-payments/toss/readyPrepare reservation payment
POST/reservation-payments/toss/confirmConfirm reservation payment
GET/reservation-payments/{id}/statusPayment status

Forms

Dynamic form builder with submissions. Contact forms, surveys, applications, etc.

Endpoints

GET/formsList forms
GET/forms/{slug}Get form schema
POST/forms/{slug}/submitSubmit form
GET/forms/{slug}/check-ipCheck IP limit
GET/forms/{slug}/submissionsList submissions
GET/my/submissionsMy submissions

SDK 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

GET/entitiesList entities
POST/entitiesCreate entity
GET/entities/{slug}Get entity
PUT/entities/{slug}Update entity
DELETE/entities/{slug}Delete entity

Record Endpoints

GET/entities/{slug}/recordsList records
POST/entities/{slug}/recordsCreate record
GET/entities/{slug}/records/{id}Get record
PUT/entities/{slug}/records/{id}Update record
DELETE/entities/{slug}/records/{id}Delete record

SDK 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

POST/chat/conversationsStart conversation
GET/chat/conversationsList my conversations
GET/chat/conversations/{id}Get conversation detail
POST/chat/conversations/{id}/messagesSend message
GET/chat/conversations/{id}/messagesGet messages
GET/chat/conversations/{id}/pollPoll for new messages
POST/chat/conversations/{id}/closeClose conversation
POST/chat/conversations/{id}/typingSend typing indicator
GET/chat/availabilityCheck agent availability

SDK 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

GET/chat/agent/conversationsList conversations
GET/chat/agent/conversations/{id}Get conversation
POST/chat/agent/conversations/{id}/messagesSend message
POST/chat/agent/conversations/{id}/assignAssign to agent
POST/chat/agent/conversations/{id}/closeClose conversation
POST/chat/agent/conversations/{id}/reopenReopen conversation
POST/chat/agent/statusUpdate agent status
GET/chat/agent/statsDashboard stats

AI Agents

AI-powered agents for automation. Configure, run, and monitor agent executions.

Endpoints

GET/agentsList available agents
GET/agents/{slug}Get agent detail
POST/agents/{slug}/configureConfigure agent
POST/agents/{slug}/runRun agent
GET/agents/{slug}/executionsList executions
GET/agents/{slug}/statsAgent stats
GET/executions/{executionId}Get execution detail

Courses / LMS

Learning management system with courses, lessons, enrollment, and progress tracking.

Public Endpoints

GET/coursesList courses
GET/courses/{slug}Get course detail
POST/courses/{slug}/enrollEnroll in course

Protected Endpoints

GET/my/coursesMy enrolled courses
GET/my/courses/{slug}My course progress
GET/my/courses/{slug}/lessons/{id}Get lesson content
POST/my/courses/{slug}/lessons/{id}/completeComplete lesson
POST/my/courses/{slug}/lessons/{id}/progressUpdate progress

More Resources