FAQ & ინსტრუქცია

1. აირჩიე ინტეგრაციის გზა

A) მხოლოდ მზა URL/embed — გალერეიდან ან API response-ის variants. B) სერვერიდან ატვირთვა API-ით (Pro+). C) Webhook + შენი backend (Pro+). D) Shopify/Woo იმპორტი (Business).

2. მაღაზია + API Key

Settings → მაღაზია (ბრენდინგი, კატალოგი). API Keys → key მაღაზიაზე (Pro+). Key მხოლოდ server-side — არა browser-ში.

3. ფოტოს დამუშავება

POST /api/v1/images (multipart) ან აპში ატვირთვა → მიიღე image id და variants[].url (thumb, full). full URL = პროდუქტის ფოტო შენს DB-ში.

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

ephoto-ში: POST /products + image_ids. შენს საიტში: შენახე full URL პროდუქტის ჩანაწერში (Shopify image URL, Woo gallery, custom DB column).

5. გამოქვეყნება

HTML: <img src="FULL_URL">. React/Next: next/image ან <img>. iframe: /embed/IMAGE_ID. published status ephoto-ში = საჯარო ლინკები.

ვის არის დეველოპერის გზამკვლევი?

რა განსხვავებაა მომხმარებელსა და დეველოპერს შორის?

მომხმარებელი ხელით ატვირთებს და გალერეიდან ჩასვამს. დეველოპერი აწყობს ავტომატიზაცია: სერვერიდან ატვირთვა, URL შენახვა DB-ში, webhook, Shopify/Woo სინქ — ეს ტაბი.

რა შემიძლია ჩავაშენო?

1) მზა ფოტოს URL შენს პროდუქტის მოდელში 2) API-ით ატვირთვა + სტატუსის polling 3) პროდუქტის შექმნა ephoto კატალოგში 4) iframe embed 5) webhook როცა პროდუქტი იქმნება 6) Shopify/Woo იმპორტი (Business).

ინტეგრაციის 4 გზა — რომელი აირჩიო?

A) URL / Embed (სწრაფი, კოდ minimum)

ephoto-ში დაამუშავე → გალერეაში variants.full URL → შენს DB/Shopify/Woo ველში. ან Embed <img>. API key არ სჭირდება. იდეალური MVP-ისთვის.

B) Public API (ავტომატური ატვირთვა)

Pro+ გეგმა. Server → POST /api/v1/images + Authorization: Bearer. Response: id, variants[].url (synchronous — poll არ სჭირდება). შენახე full URL პროდუქტში. სრული docs: /docs

C) Webhook (შენი backend რეაგირებს)

Pro+ → custom webhook URL. პროდუქტის შექმნისას ephoto POST JSON. შენი სერვერი იღებს product + image URLs და ჩაწერს შენს სისტემაში.

D) Shopify / Woo იმპორტი

Business → Integrations → credentials → პროდუქტების draft იმპორტი ephoto-ში. ხელით სინქ. ფოტოს push უკან — planned v2.

საკუთარი HTML / WordPress საიტი

სტატიკური HTML

გალერეიდან Embed კოდი ან: <img src="https://ephoto.ge/uploads/orgId/imageId/full.png" alt="პროდუქტი" style="max-width:100%;background:#fff" /> URL ჩაანაცვლე გალერეის „ლინკით“.

iframe embed გვერდი

<iframe src="https://ephoto.ge/embed/IMAGE_ID" width="400" height="400" style="border:0" title="product"></iframe> view tracking ითვლება embed გახსნისას.

WordPress + WooCommerce (პლაგინი)

ჩამოტვირთე ოფიციალური პლაგინი: /downloads/ephoto-wordpress.zip → wp-content/plugins → Activate → Settings → Ephoto → API key. WooCommerce პროდუქტზე „Process featured image“. სინქი პროდუქტების იმპორტისთვის: Business → Integrations.

Joomla

ჩამოტვირთე /downloads/ephoto-joomla.zip → Extensions → Install. System → Plugins → System - Ephoto → API key. com_ajax: ?option=com_ajax&plugin=ephoto&group=system&task=test (admin). processed URL — Media → Add from URL.

ოფიციალური პლაგინები

WordPress + WooCommerce

Download: https://ephoto.ge/downloads/ephoto-wordpress.zip 1) Install plugin 2) Settings → Ephoto → API key (Pro+) 3) Product → Ephoto box → Process featured image. Product import/sync: Business plan → Integrations (ephoto pulls products from Woo).

Joomla

Download: https://ephoto.ge/downloads/ephoto-joomla.zip Extensions → Install → System → Plugins → System - Ephoto → API key. Test: administrator/index.php?option=com_ajax&plugin=ephoto&group=system&task=test Use full URL from API in Media → Add from URL.

Shopify / OpenCart / Magento

Shopify: Business → Integrations (import). OpenCart/Magento: Public API /api/v1 + custom module (roadmap). Docs: /docs

React / Next.js პროდუქტის გვერდზე

მარტივი კომპონენტი

```tsx // fullUrl = ephoto variants.full (სრული URL ან /uploads/... path + origin) export function ProductPhoto({ fullUrl, alt }: { fullUrl: string; alt: string }) { const src = fullUrl.startsWith("http") ? fullUrl : `${process.env.NEXT_PUBLIC_SITE_URL}${fullUrl}`; return <img src={src} alt={alt} className="w-full object-contain bg-white" />; } ``` შენს Product model-ში ველი: ephotoImageUrl ან galleryUrls[].

ფოტოალბომი (რამდენიმე URL)

ephoto პროდუქტზე რამდენიც image_ids გაქვს — GET /products/:id (session) ან API → ყველა variants.full. UI-ში thumbnail grid + active image.

არ გამოიყენე API key frontend-ში

ატვირთვა მხოლოდ server action / API route-დან. Key env-ში (EPHOTO_API_KEY). Client მხოლოდ მზა URL-ს იღებს.

Node.js / PHP backend — API ატვირთვა

Node.js (fetch) — ფოტო ატვირთვა

```js const form = new FormData(); form.append("file", new Blob([buffer]), "product.jpg"); const res = await fetch("https://ephoto.ge/api/v1/images", { method: "POST", headers: { "Authorization": "Bearer " + process.env.EPHOTO_API_KEY }, body: form, }); // synchronous — response returns when ready, no polling needed const { data } = await res.json(); const fullUrl = data.variants.find(v => v.variant === "full").url; // შენახე fullUrl შენს products.image_url ველში ```

PHP (curl)

```php $ch = curl_init("https://ephoto.ge/api/v1/images"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EPHOTO_API_KEY")], CURLOPT_POSTFIELDS => ["file" => new CURLFile("/path/product.jpg")], CURLOPT_RETURNTRANSFER => true, ]); // synchronous — blocks until ready, no polling needed $json = json_decode(curl_exec($ch), true); $fullUrl = $json["data"]["variants"][0]["url"]; // ან full variant ```

პროდუქტის შექმნა ephoto-ში + შენი DB

1) POST /images → image_id + fullUrl 2) POST /api/v1/products { title_ka, image_ids: [id], price } 3) შენს DB: INSERT product SET photo_url=fullUrl, ephoto_product_id=...

სტატუსის შემოწმება

POST /api/v1/images synchronous-ია — request blocks processing-ის განმავლობაში და response ყოველთვის status: "ready" ან error-ს დააბრუნებს. GET /api/v1/images/:id შეგიძლია გამოიყენო ნებისმიერ დროს სტატუსის შესამოწმებლად.

API Key და ავტორიზაცია

Key-ის მიღება

API Keys → მაღაზია → გენერაცია (Pro+). ერთხელ სრულად ჩანს — შეინახე secrets manager-ში. Key = ერთი მაღაზია.

Header

Authorization: Bearer ephk_live_xxxxxxxx (X-Api-Key header backward compat-ისთვის ასევე მუშაობს) Key client bundle-ში არ უნდა იყოს — მხოლოდ server-side.

Base URL

Production: https://ephoto.ge/api/v1 Dev (local): http://localhost:3111/api/v1

Endpoints (v1)

ფოტო

POST /images — multipart file. GET /images, GET /images/:id — სია და variants (thumb, full).

კატალოგი

POST/GET /products, GET/PATCH/DELETE /products/:id — პროდუქტი + image_ids[]. POST/GET /categories, DELETE /categories/:id — ხე მაღაზიაზე.

products status vs categories status

products: status = "active" | "draft" — PATCH-ით იცვლება. categories-ს status არ აქვს — ყოველთვის active-ია; მართვა DELETE-ით ხდება.

ბრენდინგი

მაღაზიაზე brandEnabled=true → API upload ავტომატურად brand-ს იყენებს (2 cr). brand=false → 1 cr.

Rate limit

60 req/min per key. Header: X-RateLimit-Remaining.

რა შევინახო შენს პროექტში?

მინიმალური ველები (რეკომენდაცია)

ephoto_image_id (string UUID), image_full_url (string, CDN path ან სრული URL), ephoto_product_id (optional). შენი title, price, sku — შენს DB-ში.

URL ფორმატი

variants.full ჩვეულებრივ /uploads/{orgId}/{imageId}/full.png — საიტზე გამოყენებისას დაამატე origin: https://ephoto.ge

პროდუქტის ფოტოალბომი

რამდენი image_ids გაქვს ephoto product-ზე — იმდენი URL შენს gallery ველში (JSON array ან join table).

Webhook და პლატფორმები

Custom webhook

Pro+ Integrations → webhook URL + secret. პროდუქტის შექმნისას POST JSON (product id, images, custom_fields). შენი endpoint დააბრუნებს 200.

Shopify / WooCommerce

Business → იმპორტი ephoto-ში draft პროდუქტებად. ფოტოს ავტომატური push Shopify-ზე — planned v2. ახლა: ephoto-დან URL → Shopify Admin.

რეფერალი agency-სთვის

კლიენტს /register?ref=CODE — 20% net 12 თვე. Cookie ephoto_ref 30 დღე.

შეცდომები

401 / 403

არასწორი/revoked API key; Free გეგმა API-ს არ იძლევს.

402

credits დასრულებული ან გეგმის ლიმიტი (მაღაზიები, integration).

ფოტო failed

ფორმატი, corrupt file, ზომა >25MB. GET /images/:id error field.