Homux დეველოპერებისთვის

ვიზუალიზატორი თქვენს საიტზე

მიეცით მყიდველებს საშუალება, თქვენი პროდუქტი საკუთარ ოთახში ნახონ — პირდაპირ თქვენი საიტიდან. ღილაკი ემატება HTML-ის ორი ხაზით, ბმულები — კოდის გარეშე, კატალოგი კი REST API-ით სინქრონდება.

ვებ-ვიჯეტი

ღილაკი პროდუქტის გვერდზე

ბმულები

Instagram, Facebook, მეილი

REST API

კატალოგის წაკითხვა და მართვა

1მყიდველი აჭერს „სცადე შენს ოთახში“
2ვიზუალიზატორი იხსნება ფანჯარაში, თქვენს გვერდზე
3ტვირთავს ოთახის ფოტოს ან ირჩევს სანიმუშოს
4თქვენი პროდუქტი მაშინვე ედება ოთახს

ფანჯარაში მხოლოდ თქვენი პროდუქტები ჩანს. ყოველი გახსნა ჩანს თქვენს ანალიტიკაში.

ორი ხაზი — და მზადაა

<!-- 1. Once, on every page (before </body>) -->
<script src="https://homux.ge/embed/homux.js" data-company="your-handle" async></script>

<!-- 2. Where the button should appear -->
<div data-homux-try data-sku="WP-1042"></div>

მზა კოდი თქვენი პროდუქტებისთვის

კომპანიის პანელში: პარამეტრები → „საიტი და API“ — თქვენი handle უკვე ჩასმულია, გახსნა →

დემო

ასე გამოჩნდება თქვენს საიტზე

ქვემოთ — სადემო ონლაინ მაღაზია, რომელსაც Homux-ის სკრიპტი აქვს დამატებული. გადაერთეთ პროდუქტის გვერდსა და კატალოგს შორის, ნახეთ მობილური ვერსია, ან დააჭირეთ ღილაკს და ნახეთ, რას დაინახავს თქვენი მყიდველი.

მონიშნე, რას ამატებს Homux

kvamo.ge/ka/product/calacattaსრულ ეკრანზე

1პროდუქტის გვერდზე — დიდი ღილაკი „კალათაში დამატების“ ქვეშ<div data-homux-try data-size="lg" data-full-width …>
2კატალოგში — პატარა ღილაკი ყველა ბარათზე<div data-homux-try data-size="sm" data-theme="light" …>
3ფუტერში — ბეჯი (არასავალდებულო)<div data-homux-badge>

„ქვამო“ გამოგონილი მაღაზიაა. ყველაფერი, რაც ჩარჩოში ჩანს, მაღაზიის საკუთარი კოდია, გარდა მონიშნული ელემენტებისა — მათ Homux-ის სკრიპტი ხატავს. ღილაკები ნამდვილია: დააჭირეთ და ვიზუალიზატორი გაიხსნება ფანჯარაში, პირდაპირ მაღაზიის გვერდზე. პროდუქტების ფოტოები: FancyWalls, Homux-ის კატალოგიდან.

ვებ-ვიჯეტი

სწრაფი დაწყება

1
დარწმუნდით, რომ პროდუქტები Homux-ზეა
დაამატეთ ისინი პანელში ან API-ით. თუ თქვენს საიტზე პროდუქტებს კოდი (SKU) აქვთ, ჩაწერეთ იგივე კოდი Homux-ში — მაშინ ერთი შაბლონი ყველა პროდუქტზე იმუშავებს.
2
ჩასვით სკრიპტი ერთხელ
ყველა გვერდზე, </body>-მდე, ან საიტის „Custom code / Footer scripts“ პარამეტრში. data-company — თქვენი Homux handle.
3
განათავსეთ ღილაკი
იქ, სადაც ღილაკი უნდა გამოჩნდეს — მაგ. „კალათაში დამატების“ ქვეშ.

ღილაკი მხოლოდ მაშინ ჩნდება, როცა პროდუქტი Homux-ზე არსებობს და საჯაროა. ამიტომ უსაფრთხოა მისი ჩასმა ყველა პროდუქტის შაბლონში.

ყველა გვერდზე

<script src="https://homux.ge/embed/homux.js" data-company="your-handle" async></script>

პროდუქტის გვერდზე

<div data-homux-try data-sku="WP-1042"></div>

სცადეთ აქვე

შეავსეთ პროდუქტი, აირჩიეთ სტილი და დააკოპირეთ კოდი — გადახედვა ნამდვილი ვიჯეტია.

პროდუქტის მოძებნა

Homux პროდუქტის IDმაგალითი კატალოგიდან: Ash Staggered · FancyWallsსაკუთარი ტექსტი (არასავალდებულო)

სტილი

ზომა

ენა

მთელ სიგანეზე

ერთხელ, ყველა გვერდზე

<script src="https://homux.ge/embed/homux.js" async></script>

ღილაკის ადგილას

<div data-homux-try data-product="0BA43UGxzzDhHDkv8wpJ" data-lang="ka"></div>

ღილაკის პარამეტრები

ყველა პარამეტრი ელემენტის ატრიბუტია. data-company, data-lang, data-theme, data-size, data-open სკრიპტის ტეგზეც მუშაობს — მაშინ ყველა ღილაკზე ვრცელდება.

ატრიბუტები

data-homux-try
ამ ელემენტში გამოჩნდება ღილაკი.
data-skustring
თქვენი პროდუქტის კოდი. საჭიროებს data-company-ს (ელემენტზე ან სკრიპტზე). დიდ-პატარა ასოებს არ განასხვავებს.
data-productstring
Homux პროდუქტის ID — data-sku-ს ალტერნატივა.
data-companystring
თქვენი Homux handle, @-ის გარეშე (homux.ge/@your-handle). ჩვეულებრივ ერთხელ, სკრიპტზე იწერება.
data-openwindow | tab
window (ნაგულისხმევი) — ვიზუალიზატორი იხსნება ფანჯარაში, პირდაპირ თქვენს გვერდზე. tab — ახალ ჩანართში, homux.ge-ზე.
data-langka | en
ღილაკისა და ვიზუალიზატორის ენა. ნაგულისხმევად — გვერდის <html lang>, თუ არადა ka.
data-themebrand | dark | light
ფერები. ნაგულისხმევი: brand (ნარინჯისფერი).
data-sizesm | md | lg
ზომა. ნაგულისხმევი: md.
data-labelstring
საკუთარი ტექსტი ღილაკზე.
data-full-widthboolean
ღილაკი კონტეინერის მთელ სიგანეს იკავებს.

საკუთარი დიზაინი

ღილაკი Shadow DOM-შია, ამიტომ თქვენი საიტის CSS მას ვერ დააზიანებს. ფერები, მომრგვალება და შრიფტი CSS ცვლადებით იცვლება.

ნამდვილი ბმულია (<a>): მუშაობს კლავიატურით და ეკრანის წამკითხველით; Ctrl/⌘-ით დაჭერა ახალ ჩანართს ხსნის.
სკრიპტი async იტვირთება, cookie-ებს არ იყენებს და ბევრ ღილაკს ერთი მოთხოვნით ამოწმებს.

ყველა პარამეტრით

<div
  data-homux-try
  data-sku="WP-1042"
  data-theme="dark"
  data-size="lg"
  data-lang="en"
  data-label="See it in your room"
  data-full-width
></div>

საკუთარი დიზაინი

/* Match your site's buttons */
[data-homux-try] {
  --homux-bg: #0b5d3b;
  --homux-bg-hover: #0a4f32;
  --homux-color: #ffffff;
  --homux-border: transparent;
  --homux-radius: 6px;
  --homux-font: "Inter", sans-serif;
}

პლატფორმები

აირჩიეთ თქვენი პლატფორმა კოდის პანელში.

Shopify — Online Store → Themes → Edit code. სკრიპტი theme.liquid-ში, ღილაკი — პროდუქტის სექციაში. ვარიანტის შეცვლისას განაახლეთ data-sku და ღილაკი თავად გადაერთვება.
WooCommerce — (child) თემის functions.php ან Code Snippets პლაგინი.
Wix · Tilda · Webflow — ერთი „Embed HTML“ ბლოკი, ორივე ხაზით ერთად: ზოგი ბილდერი ბლოკს ცალკე iframe-ში ხსნის.
React · Next.js · Vue — სკრიპტი ერთხელ, ელემენტი სადაც გინდათ. ახალ ელემენტებს ვიჯეტი თავად ამჩნევს.

<!-- layout/theme.liquid, right before </body> -->
<script src="https://homux.ge/embed/homux.js" data-company="your-handle" async></script>

<!-- sections/main-product.liquid, near the Add to cart button -->
<div data-homux-try data-sku="{{ product.selected_or_first_available_variant.sku | escape }}"></div>

JavaScript და ივენთები

სკრიპტი ქმნის window.Homux ობიექტს. ივენთები ელემენტიდან ზემოთ ვრცელდება, ამიტომ ერთი listener საკმარისია.

მეთოდები

Homux.lookup(opts)Promise<product | null>
ამოწმებს, არის თუ არა პროდუქტი Homux-ზე. opts: { sku } ან { product }.
Homux.open(opts)Promise<boolean>
ხსნის ვიზუალიზატორის ფანჯარას თქვენივე ღილაკიდან; { mode: "tab" } — ახალ ჩანართში.
Homux.close()void
ხურავს ფანჯარას.
Homux.scan(root?)void
ხელახლა ეძებს ელემენტებს (ჩვეულებრივ საჭირო არ არის).

ივენთები

homux:loadeddocument
სკრიპტი მზადაა.
homux:readyelement
ღილაკი გამოჩნდა. event.detail.product — პროდუქტი.
homux:unavailableelement
პროდუქტი Homux-ზე არ არის — ღილაკი არ ჩანს.
homux:openelement · cancelable
მყიდველმა დააჭირა. event.preventDefault() გახსნას შეაჩერებს.
homux:closeelement
ვიზუალიზატორის ფანჯარა დაიხურა.

window.Homux

// The script loads async — wait for it once:
function withHomux(fn) {
  if (window.Homux) fn(window.Homux);
  else document.addEventListener('homux:loaded', () => fn(window.Homux), { once: true });
}

withHomux(async (Homux) => {
  // Is this product on Homux? → product object, or null
  const product = await Homux.lookup({ sku: 'WP-1042' });

  // Open the visualizer window from your own button
  document.querySelector('#see-in-room').addEventListener('click', () => {
    Homux.open({ sku: 'WP-1042' }); // or { sku, mode: 'tab' }
  });
});

ივენთები

// Google Analytics 4: track clicks on the Homux button
document.addEventListener('homux:open', (event) => {
  const p = event.detail.product;
  gtag('event', 'homux_try_in_room', { item_id: p.sku || p.id, item_name: p.name });
});

// Hide your own "visualize" label when the product is not on Homux
document.addEventListener('homux:unavailable', (event) => {
  event.target.closest('.visualize-box')?.remove();
});

ბმულები კოდის გარეშე

ჩვეულებრივი ბმული, რომელიც ვიზუალიზატორს ამ პროდუქტით ხსნის: Instagram-ის bio და სთორის სტიკერი, Facebook, WhatsApp, Viber, მეილი. თუ პროდუქტი ვერ მოიძებნა, ბმული თქვენს Homux გვერდზე ან კატალოგზე გადაიყვანს — შეცდომაზე არასოდეს.

Query პარამეტრები

productstring
Homux პროდუქტის ID.
company + skustring
თქვენი handle და პროდუქტის კოდი — product-ის ნაცვლად.
langka | en
ვიზუალიზატორის ენა.

URL

https://homux.ge/api/v1/try?product=PRODUCT_ID

Homux ბეჯი

პატარა წარწერა „ვიზუალიზაცია Homux-ის მიერ“, რომელიც თქვენს Homux გვერდზე გადადის. იყენებს იმავე სკრიპტს. ძველი homux-badge.js-იც კვლავ მუშაობს.

<div data-homux-badge></div>
<div data-homux-badge data-theme="dark" data-lang="en"></div>

პროდუქტის კოდები (SKU)

სად: პანელი → კატალოგი → პროდუქტი → რედაქტირება → „პროდუქტის კოდი (SKU)“. API-ით — sku ველი.
კოდი კომპანიაში უნიკალურია, მაქს. 64 სიმბოლო. დიდ-პატარა ასოები არ განსხვავდება: WP-1042 = wp-1042.
SKU არ გაქვთ? გამოიყენეთ Homux ID — პროდუქტის გვერდის მისამართის ბოლო ნაწილი: homux.ge/ka/catalog/aBc123

API reference

შესავალი

Homux API — REST, JSON. საჯარო კატალოგის წაკითხვას გასაღები არ სჭირდება და ბრაუზერიდანაც მუშაობს (CORS). პროდუქტების დამატება, შეცვლა და წაშლა — საიდუმლო გასაღებით, მხოლოდ სერვერიდან.

პასუხი ყოველთვის { "data": … }; სიებს აქვს has_more, next_cursor და total. საჯარო პასუხები ქეშში ინახება — ცვლილებას 3 წუთამდე შეიძლება დასჭირდეს.

v1 სტაბილურია. ახალი ველები შეიძლება დაემატოს გაფრთხილების გარეშე — უცნობი ველები უბრალოდ გამოტოვეთ. არსებულის შეცვლა მხოლოდ v2-ში მოხდება.

Base URL

https://homux.ge/api/v1

Endpoints

GET/companies/{handle}
GET/companies/{handle}/products
GET/products/{id}
GET/products?ids=…
PUT/products/by-sku/{sku}
POST/products
PATCH/products/{id}
GET/products/by-sku/{sku}
DEL/products/{id}
GET/me
GET/try

ავტორიზაცია

გასაღებს ქმნით კომპანიის პანელში: პარამეტრები → „საიტი და API“ → API გასაღებები. გაგზავნეთ ჰედერად: Authorization: Bearer hx_live_…

გასაღები მხოლოდ სერვერზე

გასაღები მხოლოდ შექმნისას ჩანს. არასოდეს ჩასვათ ის საიტის JavaScript-ში — ბრაუზერიდან გასაღებიანი მოთხოვნა განზრახ იბლოკება. თუ გასაღები გაჟონა, გააუქმეთ და შექმენით ახალი.

GETგასაღების გაგზავნა

curl "https://homux.ge/api/v1/me" \
  -H "Authorization: Bearer $HOMUX_API_KEY"

შეცდომები

შეცდომას ყოველთვის აქვს მანქანისთვის წაკითხვადი code და ადამიანისთვის message. ყველა პასუხს აქვს X-Request-Id ჰედერი — მიუთითეთ ის, როცა დახმარებას ითხოვთ.

კოდები

bad_request400
არასწორი პარამეტრი ან JSON.
unauthorized401
გასაღები აკლია, არასწორია ან გაუქმებულია.
subscription_required402
გამოწერა არააქტიურია — ცვლილებები შეჩერებულია.
plan_limit_reached403
გეგმის პროდუქტების ლიმიტი ამოიწურა.
not_found · company_not_found404
პროდუქტი ან კომპანია ვერ მოიძებნა.
sku_taken409
ეს SKU სხვა პროდუქტს აქვს (details.product_id).
validation_failed422
ველები არასწორია — თითოეული ახსნილია details.fields-ში.
image_invalid · image_invalid_url · image_too_small · image_too_large422
სურათის პრობლემა — message აღწერს, რა უნდა შეიცვალოს.
image_unreachable424
image_url ვერ ჩამოიტვირთა.
rate_limited429
ძალიან ბევრი მოთხოვნა — დაელოდეთ Retry-After წამს.

422 მაგალითი

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "details": {
      "fields": {
        "price": "A number from 0 to 1000000 (GEL)."
      }
    },
    "docs": "https://homux.ge/developers"
  }
}

ლიმიტები და გვერდები

საჯარო წაკითხვა: 300 მოთხოვნა/წთ თითო IP-ზე. გასაღებით: 120 მოთხოვნა/წთ თითო გასაღებზე.
გადაჭარბებისას — 429 და Retry-After ჰედერი წამებში.
სიები: limit (1–100, ნაგულისხმევი 50) და cursor წინა პასუხის next_cursor-იდან. has_more: false — ბოლო გვერდია.

GETშემდეგი გვერდი

curl "https://homux.ge/api/v1/companies/your-handle/products?limit=50&cursor=Mg"

პასუხი

{
  "data": [
    "…"
  ],
  "has_more": true,
  "next_cursor": "MTAw",
  "total": 148
}

ობიექტი

პროდუქტის ობიექტი

ველები

idstring
Homux პროდუქტის ID.
skustring | null
თქვენი კოდი, თუ მითითებულია.
namestring
პროდუქტის სახელი.
categorywalls | floors | doors
ოთახის ზედაპირი.
typestring
პროდუქტის ტიპი — იხ. ტიპები.
subtype, material, stylestring | null
ფილტრების მონაცემები.
finishstring[]
ზედაპირი, მაგ. ["Matte"].
colorstring | null
საშუალო ფერი, HEX.
sizeobject | null
სურათზე ნაჩვენები ფართობის რეალური ზომა.
size_labelstring | null
ზომა ტექსტად, მაგ. "53 × 53 cm".
priceobject | null
ფასი, ზუსტად ისე, როგორც მყიდველი ხედავს.
promo_textstring | null
შეთავაზების ხაზი.
image_urlstring
ტექსტურა, ≤ 2048 px.
thumbnail_urlstring
480 px მინიატურა.
companyobject
ვისი პროდუქტია.
urlsobject
მზა ბმულები.
created_at, updated_atISO 8601
დროის ნიშნულები.

პროდუქტის ობიექტი

{
  "id": "aBc123",
  "sku": "WP-1042",
  "name": "Linen Grey",
  "category": "walls",
  "type": "Wallpaper",
  "subtype": null,
  "material": "Vinyl",
  "style": "Modern",
  "finish": [
    "Matte",
    "Textured"
  ],
  "color": "#b3b3ab",
  "size": {
    "width": 53,
    "height": 53,
    "unit": "cm"
  },
  "size_label": "53 × 53 cm",
  "price": {
    "amount": 27.99,
    "compare_at": null,
    "base_amount": 28,
    "currency": "GEL"
  },
  "promo_text": null,
  "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
  "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
  "company": {
    "id": "Xk2pQ8…",
    "handle": "your-handle",
    "name": "Your Store"
  },
  "urls": {
    "page": "https://homux.ge/ka/catalog/aBc123",
    "try_on": "https://homux.ge/api/v1/try?product=aBc123"
  },
  "created_at": "2026-09-30T10:12:00.000Z",
  "updated_at": "2026-10-02T08:40:00.000Z"
}

კომპანიის მიღება

GET/v1/companies/{handle}

კომპანიის საჯარო პროფილი და პროდუქტების რაოდენობა. გასაღები არ სჭირდება.

Path პარამეტრები

handlestringსავალდებულო
Homux handle, @-ის გარეშე.

რას აბრუნებს

dataobject
კომპანია, ან 404 company_not_found.

GETმოთხოვნა

curl "https://homux.ge/api/v1/companies/your-handle"

პასუხი

{
  "data": {
    "id": "Xk2pQ8…",
    "handle": "your-handle",
    "name": "Your Store",
    "bio": "Wallpaper and tiles in Tbilisi",
    "logo_url": "https://firebasestorage.googleapis.com/…/logo.jpg",
    "website": "https://yourstore.ge",
    "location": "Tbilisi",
    "page_url": "https://homux.ge/ka/@your-handle",
    "product_count": 148
  }
}

კომპანიის პროდუქტები

GET/v1/companies/{handle}/products

კომპანიის საჯარო პროდუქტები, ახლიდან ძველისკენ. გასაღები არ სჭირდება.

Query პარამეტრები

categorywalls | floors | doors
ზედაპირით გაფილტვრა.
typestring
ტიპით გაფილტვრა, მაგ. Laminate.
skustring
კონკრეტული SKU-ები, მძიმით (მაქს. 50).
limitinteger
1–100, ნაგულისხმევი 50.
cursorstring
next_cursor წინა პასუხიდან.
langka | en
urls-ის ენა.

GETმოთხოვნა

curl "https://homux.ge/api/v1/companies/your-handle/products?category=walls&limit=2"

პასუხი

{
  "data": [
    {
      "id": "aBc123",
      "sku": "WP-1042",
      "name": "Linen Grey",
      "category": "walls",
      "type": "Wallpaper",
      "subtype": null,
      "material": "Vinyl",
      "style": "Modern",
      "finish": [
        "Matte",
        "Textured"
      ],
      "color": "#b3b3ab",
      "size": {
        "width": 53,
        "height": 53,
        "unit": "cm"
      },
      "size_label": "53 × 53 cm",
      "price": {
        "amount": 27.99,
        "compare_at": null,
        "base_amount": 28,
        "currency": "GEL"
      },
      "promo_text": null,
      "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
      "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
      "company": {
        "id": "Xk2pQ8…",
        "handle": "your-handle",
        "name": "Your Store"
      },
      "urls": {
        "page": "https://homux.ge/ka/catalog/aBc123",
        "try_on": "https://homux.ge/api/v1/try?product=aBc123"
      },
      "created_at": "2026-09-30T10:12:00.000Z",
      "updated_at": "2026-10-02T08:40:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "Mg",
  "total": 61
}

პროდუქტის მიღება

GET/v1/products/{id}

ერთი საჯარო პროდუქტი Homux ID-ით.

Path პარამეტრები

idstringსავალდებულო
Homux პროდუქტის ID.

GETმოთხოვნა

curl "https://homux.ge/api/v1/products/aBc123"

პასუხი

{
  "data": {
    "id": "aBc123",
    "sku": "WP-1042",
    "name": "Linen Grey",
    "category": "walls",
    "type": "Wallpaper",
    "subtype": null,
    "material": "Vinyl",
    "style": "Modern",
    "finish": [
      "Matte",
      "Textured"
    ],
    "color": "#b3b3ab",
    "size": {
      "width": 53,
      "height": 53,
      "unit": "cm"
    },
    "size_label": "53 × 53 cm",
    "price": {
      "amount": 27.99,
      "compare_at": null,
      "base_amount": 28,
      "currency": "GEL"
    },
    "promo_text": null,
    "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
    "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
    "company": {
      "id": "Xk2pQ8…",
      "handle": "your-handle",
      "name": "Your Store"
    },
    "urls": {
      "page": "https://homux.ge/ka/catalog/aBc123",
      "try_on": "https://homux.ge/api/v1/try?product=aBc123"
    },
    "created_at": "2026-09-30T10:12:00.000Z",
    "updated_at": "2026-10-02T08:40:00.000Z"
  }
}

რამდენიმე პროდუქტის მიღება

GET/v1/products?ids=…

რამდენიმე პროდუქტი ერთი მოთხოვნით (მაქს. 50). ვერნაპოვნი ID-ები უბრალოდ გამოტოვებულია.

Query პარამეტრები

idsstringსავალდებულო
ID-ები მძიმით.

GETმოთხოვნა

curl "https://homux.ge/api/v1/products?ids=aBc123,dEf456"

პასუხი

{
  "data": [
    {
      "id": "aBc123",
      "sku": "WP-1042",
      "name": "Linen Grey",
      "category": "walls",
      "type": "Wallpaper",
      "subtype": null,
      "material": "Vinyl",
      "style": "Modern",
      "finish": [
        "Matte",
        "Textured"
      ],
      "color": "#b3b3ab",
      "size": {
        "width": 53,
        "height": 53,
        "unit": "cm"
      },
      "size_label": "53 × 53 cm",
      "price": {
        "amount": 27.99,
        "compare_at": null,
        "base_amount": 28,
        "currency": "GEL"
      },
      "promo_text": null,
      "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
      "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
      "company": {
        "id": "Xk2pQ8…",
        "handle": "your-handle",
        "name": "Your Store"
      },
      "urls": {
        "page": "https://homux.ge/ka/catalog/aBc123",
        "try_on": "https://homux.ge/api/v1/try?product=aBc123"
      },
      "created_at": "2026-09-30T10:12:00.000Z",
      "updated_at": "2026-10-02T08:40:00.000Z"
    }
  ]
}

შექმნა ან განახლება SKU-თ

PUT/v1/products/by-sku/{sku}

სინქრონიზაციისთვის რეკომენდებული

ქმნის პროდუქტს ამ SKU-თ, ან ანახლებს არსებულს — განმეორებით გაშვება უსაფრთხოა. პასუხი: 201 (შეიქმნა) ან 200 (განახლდა), "created": true/false.

საჭიროებს API გასაღებს.

Path პარამეტრები

skustringსავალდებულო
თქვენი პროდუქტის კოდი.

Body პარამეტრები

namestring ≤ 200სავალდებულო
პროდუქტის სახელი.
categorywalls | floors | doorsსავალდებულო
ოთახის რომელ ზედაპირზე იდება.
typestringსავალდებულო
პროდუქტის ტიპი — იხ. ტიპები. მიიღება სლაგიც: wood-flooring.
image_urlhttps URLსავალდებულო შექმნისას
ზედაპირის ფოტო (JPEG, PNG, WebP, AVIF, GIF; მაქს. 20 MB, 40 MP; მოკლე მხარე მინ. 200 px). იგივე URL-ის ხელახლა გაგზავნისას სურათი თავიდან არ იტვირთება.
image_base64string
იგივე სურათი base64-ით, თუ საჯარო URL არ გაქვთ.
pricenumber
ფასი ლარში (0 – 1 000 000).
compare_at_pricenumber
ძველი, გადახაზული ფასი. price-ზე მეტი უნდა იყოს.
promo_textstring ≤ 120
შეთავაზების ხაზი ფასის ქვეშ.
sizeobject
სურათზე ნაჩვენები ფართობის რეალური ზომა (თითო მხარე ≤ 10 მ). მიუთითეთ ერთი ფილის ან შპალერის ერთი რაპორტის ზომა, არა რულონის სიგრძე.
finishstring[]
ზედაპირი, მაგ. ["Matte", "Textured"] (მაქს. 10).
material, style, subtypestring ≤ 60
მასალა (Porcelain, Oak), სტილი (Modern), ქვეტიპი (Mosaic).

PUTმოთხოვნა

curl -X PUT "https://homux.ge/api/v1/products/by-sku/WP-1042" \
  -H "Authorization: Bearer $HOMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Linen Grey",
  "category": "walls",
  "type": "Wallpaper",
  "price": 26,
  "compare_at_price": 28,
  "image_url": "https://yourstore.ge/images/wp-1042-swatch.jpg"
}'

200 · პასუხი

{
  "data": {
    "id": "aBc123",
    "sku": "WP-1042",
    "name": "Linen Grey",
    "category": "walls",
    "type": "Wallpaper",
    "subtype": null,
    "material": "Vinyl",
    "style": "Modern",
    "finish": [
      "Matte",
      "Textured"
    ],
    "color": "#b3b3ab",
    "size": {
      "width": 53,
      "height": 53,
      "unit": "cm"
    },
    "size_label": "53 × 53 cm",
    "price": {
      "amount": 25.99,
      "compare_at": 28,
      "base_amount": 26,
      "currency": "GEL"
    },
    "promo_text": null,
    "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
    "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
    "company": {
      "id": "Xk2pQ8…",
      "handle": "your-handle",
      "name": "Your Store"
    },
    "urls": {
      "page": "https://homux.ge/ka/catalog/aBc123",
      "try_on": "https://homux.ge/api/v1/try?product=aBc123"
    },
    "created_at": "2026-09-30T10:12:00.000Z",
    "updated_at": "2026-10-02T08:40:00.000Z"
  },
  "created": false
}

პროდუქტის შექმნა

POST/v1/products

საჭიროებს API გასაღებს. API-ით შექმნილი პროდუქტები ზუსტად ისე მუშაობს, როგორც პანელიდან ატვირთული: კატალოგში, ვიზუალიზატორში, QR ეტიკეტებსა და ანალიტიკაში.

Body პარამეტრები

namestring ≤ 200სავალდებულო
პროდუქტის სახელი.
categorywalls | floors | doorsსავალდებულო
ოთახის რომელ ზედაპირზე იდება.
typestringსავალდებულო
პროდუქტის ტიპი — იხ. ტიპები. მიიღება სლაგიც: wood-flooring.
image_urlhttps URLსავალდებულო შექმნისას
ზედაპირის ფოტო (JPEG, PNG, WebP, AVIF, GIF; მაქს. 20 MB, 40 MP; მოკლე მხარე მინ. 200 px). იგივე URL-ის ხელახლა გაგზავნისას სურათი თავიდან არ იტვირთება.
image_base64string
იგივე სურათი base64-ით, თუ საჯარო URL არ გაქვთ.
skustring ≤ 64
თქვენი პროდუქტის კოდი; კომპანიაში უნიკალური.
pricenumber
ფასი ლარში (0 – 1 000 000).
compare_at_pricenumber
ძველი, გადახაზული ფასი. price-ზე მეტი უნდა იყოს.
promo_textstring ≤ 120
შეთავაზების ხაზი ფასის ქვეშ.
sizeobject
სურათზე ნაჩვენები ფართობის რეალური ზომა (თითო მხარე ≤ 10 მ). მიუთითეთ ერთი ფილის ან შპალერის ერთი რაპორტის ზომა, არა რულონის სიგრძე.
finishstring[]
ზედაპირი, მაგ. ["Matte", "Textured"] (მაქს. 10).
material, style, subtypestring ≤ 60
მასალა (Porcelain, Oak), სტილი (Modern), ქვეტიპი (Mosaic).

სურათები

ფილა, შპალერი, ლამინატი: ზედაპირის ბრტყელი ფოტო, პირდაპირ კუთხით, თანაბარი განათებით, ჩრდილისა და წყლის ნიშნის გარეშე. იდეალურია უწყვეტი ფრაგმენტი.
კარი: მხოლოდ კარი, სწორი კუთხით, სასურველია PNG გამჭვირვალე ფონით.
რეკომენდებულია 1500 px ან მეტი. Homux ინახავს 2048 px ტექსტურას, 480 px მინიატურას და ორიგინალს.

გეგმის ლიმიტები

API-ით დამატებული პროდუქტები გეგმის ლიმიტში ითვლება (Starter — 150, Growth — 600, Scale — ულიმიტო). ლიმიტზე — 403 plan_limit_reached; შეჩერებული გამოწერისას — 402 subscription_required. წაკითხვა და ღილაკი ორივე შემთხვევაში მუშაობს.

POSTმოთხოვნა

curl -X POST "https://homux.ge/api/v1/products" \
  -H "Authorization: Bearer $HOMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Linen Grey",
  "category": "walls",
  "type": "Wallpaper",
  "sku": "WP-1042",
  "price": 28,
  "size": {
    "width": 53,
    "height": 53,
    "unit": "cm"
  },
  "finish": [
    "Matte",
    "Textured"
  ],
  "image_url": "https://yourstore.ge/images/wp-1042-swatch.jpg"
}'

201 · პასუხი

{
  "data": {
    "id": "aBc123",
    "sku": "WP-1042",
    "name": "Linen Grey",
    "category": "walls",
    "type": "Wallpaper",
    "subtype": null,
    "material": "Vinyl",
    "style": "Modern",
    "finish": [
      "Matte",
      "Textured"
    ],
    "color": "#b3b3ab",
    "size": {
      "width": 53,
      "height": 53,
      "unit": "cm"
    },
    "size_label": "53 × 53 cm",
    "price": {
      "amount": 27.99,
      "compare_at": null,
      "base_amount": 28,
      "currency": "GEL"
    },
    "promo_text": null,
    "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
    "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
    "company": {
      "id": "Xk2pQ8…",
      "handle": "your-handle",
      "name": "Your Store"
    },
    "urls": {
      "page": "https://homux.ge/ka/catalog/aBc123",
      "try_on": "https://homux.ge/api/v1/try?product=aBc123"
    },
    "created_at": "2026-09-30T10:12:00.000Z",
    "updated_at": "2026-10-02T08:40:00.000Z"
  }
}

პროდუქტის შეცვლა

PATCH/v1/products/{id}

საჭიროებს API გასაღებს. ცვლის მხოლოდ გაგზავნილ ველებს; null არასავალდებულო ველს ასუფთავებს. ველები — იგივე, რაც შექმნისას.

Path პარამეტრები

idstringსავალდებულო
Homux პროდუქტის ID.

PATCHმოთხოვნა

curl -X PATCH "https://homux.ge/api/v1/products/aBc123" \
  -H "Authorization: Bearer $HOMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "price": 24,
  "promo_text": "-15% this week",
  "compare_at_price": null
}'

პასუხი

{
  "data": {
    "id": "aBc123",
    "sku": "WP-1042",
    "name": "Linen Grey",
    "category": "walls",
    "type": "Wallpaper",
    "subtype": null,
    "material": "Vinyl",
    "style": "Modern",
    "finish": [
      "Matte",
      "Textured"
    ],
    "color": "#b3b3ab",
    "size": {
      "width": 53,
      "height": 53,
      "unit": "cm"
    },
    "size_label": "53 × 53 cm",
    "price": {
      "amount": 23.99,
      "compare_at": null,
      "base_amount": 24,
      "currency": "GEL"
    },
    "promo_text": "-15% this week",
    "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
    "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
    "company": {
      "id": "Xk2pQ8…",
      "handle": "your-handle",
      "name": "Your Store"
    },
    "urls": {
      "page": "https://homux.ge/ka/catalog/aBc123",
      "try_on": "https://homux.ge/api/v1/try?product=aBc123"
    },
    "created_at": "2026-09-30T10:12:00.000Z",
    "updated_at": "2026-10-02T08:40:00.000Z"
  }
}

პროდუქტის მიღება SKU-თ

GET/v1/products/by-sku/{sku}

საჭიროებს API გასაღებს. თქვენი პროდუქტი SKU-თ — დამალულიც.

GETმოთხოვნა

curl "https://homux.ge/api/v1/products/by-sku/WP-1042" \
  -H "Authorization: Bearer $HOMUX_API_KEY"

პასუხი

{
  "data": {
    "id": "aBc123",
    "sku": "WP-1042",
    "name": "Linen Grey",
    "category": "walls",
    "type": "Wallpaper",
    "subtype": null,
    "material": "Vinyl",
    "style": "Modern",
    "finish": [
      "Matte",
      "Textured"
    ],
    "color": "#b3b3ab",
    "size": {
      "width": 53,
      "height": 53,
      "unit": "cm"
    },
    "size_label": "53 × 53 cm",
    "price": {
      "amount": 27.99,
      "compare_at": null,
      "base_amount": 28,
      "currency": "GEL"
    },
    "promo_text": null,
    "image_url": "https://firebasestorage.googleapis.com/…/aBc123.jpg",
    "thumbnail_url": "https://firebasestorage.googleapis.com/…/aBc123_thumb.webp",
    "company": {
      "id": "Xk2pQ8…",
      "handle": "your-handle",
      "name": "Your Store"
    },
    "urls": {
      "page": "https://homux.ge/ka/catalog/aBc123",
      "try_on": "https://homux.ge/api/v1/try?product=aBc123"
    },
    "created_at": "2026-09-30T10:12:00.000Z",
    "updated_at": "2026-10-02T08:40:00.000Z"
  }
}

პროდუქტის წაშლა

DELETE/v1/products/{id}

საჭიროებს API გასაღებს. შლის პროდუქტს და მის სურათებს. დაბეჭდილი QR კოდი ამ პროდუქტისთვის აღარ იმუშავებს.

DELმოთხოვნა

curl -X DELETE "https://homux.ge/api/v1/products/aBc123" \
  -H "Authorization: Bearer $HOMUX_API_KEY"

პასუხი

{
  "data": {
    "id": "aBc123",
    "deleted": true
  }
}

გასაღების შემოწმება

GET/v1/me

საჭიროებს API გასაღებს. რომელ კომპანიას ეკუთვნის გასაღები, რა გეგმაა და რამდენი პროდუქტის დამატება შეიძლება.

GETმოთხოვნა

curl "https://homux.ge/api/v1/me" \
  -H "Authorization: Bearer $HOMUX_API_KEY"

პასუხი

{
  "data": {
    "company": {
      "id": "Xk2pQ8…",
      "handle": "your-handle",
      "name": "Your Store",
      "bio": "Wallpaper and tiles in Tbilisi",
      "logo_url": "https://firebasestorage.googleapis.com/…/logo.jpg",
      "website": "https://yourstore.ge",
      "location": "Tbilisi",
      "page_url": "https://homux.ge/ka/@your-handle"
    },
    "plan": "growth",
    "write_access": true,
    "products": {
      "count": 148,
      "limit": 600
    }
  }
}

ვიზუალიზატორის ბმული

GET/v1/try

ბრაუზერისთვის განკუთვნილი ბმული: ითვლის გახსნას და გადაჰყავს ვიზუალიზატორზე. პარამეტრები — ბმულებში.

302 Location

GET https://homux.ge/api/v1/try?product=aBc123&lang=en

HTTP/2 302
location: https://homux.ge/en/room-redesign?material=aBc123&source=widget

პროდუქტის ტიპები

wallscategory
Wallpaper, Stone, Brick, Tile, Panel, Wood Cladding, Plaster, Paint, Other
floorscategory
Wood Flooring, Laminate, Vinyl, Tile, Stone, Carpet, Concrete, Resin, Rubber, Cork, Decking, Linoleum, Other
doorscategory
Hinged, Sliding, Folding, Pivot, Entry, Glass Door, Garage Door, Other

რესურსები

სინქრონიზაციის მაგალითი

სკრიპტი, რომელიც თქვენს ონლაინ მაღაზიას ღამით Homux-თან ასინქრონებს. PUT by-sku იდემპოტენტურია — განმეორებით გაშვება უსაფრთხოა.

გაყიდვიდან ამოღებული პროდუქტების წასაშლელად წაიკითხეთ თქვენი Homux პროდუქტები და წაშალეთ ის, ვისი SKU-ც თქვენს სიაში აღარ არის.

ღამის სინქრონიზაცია

// sync-homux.mjs — run nightly (Node 18+):  HOMUX_API_KEY=hx_live_… node sync-homux.mjs
const API = 'https://homux.ge/api/v1';
const headers = { Authorization: `Bearer ${process.env.HOMUX_API_KEY}`, 'Content-Type': 'application/json' };

const products = await loadMyProducts(); // ← your shop database or export

for (const p of products) {
  const res = await fetch(`${API}/products/by-sku/${encodeURIComponent(p.sku)}`, {
    method: 'PUT',
    headers,
    body: JSON.stringify({
      name: p.title,
      category: 'walls',            // walls | floors | doors
      type: 'Wallpaper',            // see Product types
      price: p.price,
      image_url: p.swatchImageUrl,  // unchanged URL → not downloaded again
      size: { width: 53, height: 53, unit: 'cm' },
    }),
  });
  if (!res.ok) {
    const { error } = await res.json();
    console.error(p.sku, res.status, error.code, error.message, error.details ?? '');
  }
  if (res.status === 429) await new Promise((r) => setTimeout(r, 30_000));
}

ანალიტიკა

პანელის ანალიტიკაში ჩანს „საიტიდან გადასვლები“ — რამდენჯერ გახსნეს ვიზუალიზატორი თქვენი ღილაკიდან ან ბმულიდან, ამ თვეში და სულ.

ბოტები, ბმულის გადახედვები (Facebook, WhatsApp…) და ერთი ვიზიტორის განმეორებითი დაჭერები 10 წუთში არ ითვლება.
QR სკანები მხოლოდ დაბეჭდილ QR ეტიკეტებს ითვლის; რედიზაინები — როცა მყიდველი თქვენს პროდუქტს ოთახში იყენებს.
საკუთარი ანალიტიკისთვის — homux:open ივენთი.

დახმარება

ღილაკი არ ჩანს?

გახსენით ბრაუზერის კონსოლი (F12): data-homux-state გეტყვით მიზეზს — unavailable (პროდუქტი ვერ მოიძებნა) ან error.
შეამოწმეთ handle და SKU: https://homux.ge/api/v1/companies/your-handle/products?sku=WP-1042 — ცარიელი data ნიშნავს, რომ ასეთი პროდუქტი არ არის.
თუ საიტს Content-Security-Policy აქვს, დაუშვით https://homux.ge — script-src-ში, connect-src-სა და frame-src-ში.
ახლად დამატებულ ან შეცვლილ პროდუქტს გამოჩენამდე 3 წუთამდე შეიძლება დასჭირდეს.

დაგვიკავშირდით

მოგვწერეთ app.homux@gmail.com — მიუთითეთ handle და, API-ის შემთხვევაში, X-Request-Id. ინტეგრაციაში დაგეხმარებით.

ცვლილებები

2026-10-10widget 1.1
ღილაკი ვიზუალიზატორს ფანჯარაში ხსნის, პირდაპირ თქვენს საიტზე, მხოლოდ თქვენი პროდუქტებით, და პროდუქტი ავტომატურად ედება ოთახს. ახალი: data-open="tab", Homux.close(), homux:close.
2026-10-09v1
პირველი ვერსია: homux.js (ღილაკი, ბეჯი, JavaScript API), ბმულები, საჯარო კატალოგის API, კატალოგის მართვა გასაღებით, SKU ველი, საიტიდან გადასვლების ანალიტიკა.