API REFERANSI

Nuvi REST API

Tüm Nuvi platformu için REST uçları — Medusa v2 ticaret yüzeyi, her modül için Nuvi uzantıları (blog, sayfa, form, medya, arama, marka, tema, yerelleştirme, kur, metafield, yönlendirme, etkinlik, seyahat, abonelik, teklif, e-posta pazarlama, izleme, çerez onayı), sosyal giriş (Google, Apple, Facebook, GitHub, Microsoft) ve /admin/ai/* + /v1/* uçlarından erişilen, kendi model anahtarınla (OpenAI, Gemini, DeepL, ElevenLabs) veya kullandıkça öde kredileriyle çalışan 24 yetenekli AI asistan.

Temel URLhttps://usenuvi.com/api

Kimlik Doğrulama

Storefront çağrıları publishable API anahtarı ile (`x-publishable-api-key` header) yetkilendirilir. Müşteri kapsamlı çağrılar Medusa v2 auth uçlarından alınan JWT bearer ekler. Admin çağrıları admin JWT ister.

POST/auth/customer/emailpass

E-posta + parola ile müşteri JWT oluştur

Örnek istek
curl -X POST https://usenuvi.com/api/auth/customer/emailpass \
  -H "x-publishable-api-key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••"}'
POST/auth/customer/emailpass/register

Yeni müşteri kaydı oluştur

DELETE/auth/session

Mevcut oturumu sonlandır

Sosyal Giriş

Tenant başına OAuth 2.0 / OpenID Connect — Google, Apple, Facebook, GitHub ve Microsoft. Storefront akışı `/auth/social/{provider}/start`'a yönlendirerek başlatır; sağlayıcı `/auth/social/{provider}/callback`'e döner ve müşteri JWT'si storefront cookie'sine yazılır. Apple `response_mode=form_post` (POST callback) kullanır. State + PKCE Redis'te 10 dakika TTL ile saklanır.

GET/store/auth/social/:provider/start

OAuth akışını başlat — `{ authorization_url }` döner

Örnek istek
curl "https://usenuvi.com/api/store/auth/social/google/start?return_to=/account" \
  -H "x-publishable-api-key: pk_live_..."
GET/store/auth/social/:provider/callback

Code + state takası → `{ token, customer_id, is_new_link, return_to }`. Token'ı storefront'una `nuvi_customer_token` cookie olarak yaz.

POST/store/auth/social/apple/callback

Apple form_post varyantı — aynı yanıt şekli, body `application/x-www-form-urlencoded`

GET/store/auth/social/linked-accounts

Yetkili müşterinin bağlı sağlayıcılarını listele (avatar, email, last_login_at). Müşteri JWT'si gerekir.

DELETE/store/auth/social/linked-accounts/:id

Bir sağlayıcının bağlantısını kaldır. Linked-account kayıtları müşteri bazlıdır; başka müşterinin kaydına erişim 404 döner.

Ürünler

Standart Medusa v2 ürün uçları. Varyant, fiyat ve stok satır içi döner. Tam metin arama için ayrı /store/search ucunu kullan (MeiliSearch ile).

GET/store/products

Filtre ile ürün listele (koleksiyon, kategori, bölge, fiyat aralığı)

Örnek istek
curl "https://usenuvi.com/api/store/products?limit=20&offset=0" \
  -H "x-publishable-api-key: pk_live_..."
GET/store/products/:id

Tek ürünü id ya da handle ile getir

GET/store/product-templates

Admin ürün editörü için ürün şablonlarını listele

GET/store/collections

Ürün koleksiyonlarını listele (Medusa varsayılan)

GET/store/categories

Ürün kategorilerini listele (Medusa varsayılan)

GET/store/products/:product_id/reviews

Bir ürünün onaylı yorumlarını listele (sayfalı, sıralı)

POST/store/products/:product_id/reviews

Yeni yorum gönder (moderasyona kadar pending)

Sepet & Ödeme

Standart Medusa sepet uçları + etkinlik bileti ve tur rezervasyonu için Nuvi uzantıları. Ödeme oturumları kendi Stripe / Iyzico hesabına karşı kurulur.

POST/store/carts

Boş sepet oluştur

POST/store/carts/:id/line-items

Ürün satır öğesi ekle

POST/store/carts/:id/event-items

Etkinlik biletini satır öğesi olarak ekle (Nuvi)

DELETE/store/carts/:id/event-items/:lineItemId

Etkinlik bileti satır öğesini kaldır

POST/store/carts/:id/tour-items

Tur rezervasyonu satır öğesi ekle (Nuvi)

DELETE/store/carts/:id/tour-items/:lineItemId

Tur satır öğesini kaldır

POST/store/carts/:id/payment-sessions

Mevcut sağlayıcılar için ödeme oturumu kur

POST/store/carts/:id/complete

Sepeti siparişe dönüştür

Örnek istek
curl -X POST https://usenuvi.com/api/store/carts/cart_01.../complete \
  -H "x-publishable-api-key: pk_live_..."
GET/store/checkout-config

Aktif ödeme yapılandırması: aktif alanlar, ödeme sağlayıcıları, kargo seçenekleri

GET/store/payment-config

Bölge bazlı ödeme sağlayıcı yapılandırması

GET/store/bank-info

Storefront için havale ödeme talimatları

Siparişler

Standart Medusa sipariş uçları + müşteri tarafı iptal ucu.

GET/store/orders/me

Yetkili müşterinin siparişlerini listele

GET/store/orders/:id

Siparişi id ile getir

POST/store/orders/:id/cancel

Siparişi iptal et (iptal süresi içinde)

Müşteriler

Standart Medusa müşteri uçları. Yetkili müşteri kendi profilini ve adreslerini yönetebilir.

GET/store/customers/me

Mevcut müşteri profilini getir

POST/store/customers/me

Profil alanlarını güncelle

POST/store/customers/me/addresses

Kargo adresi ekle

Abonelikler (tekrarlayan)

Abonelik modülü uçları — mevcut planları listele, müşteri aboneliği oluştur / yönet, yaşam döngüsü işlemleri (duraklat, devam et, plan değiştir, iptal).

GET/store/subscription-plans

Mevcut abonelik planlarını listele

GET/store/subscriptions

Yetkili müşterinin aboneliklerini listele

POST/store/subscriptions

Yeni abonelik oluştur

GET/store/subscriptions/:id

Aboneliği getir

POST/store/subscriptions/checkout

Abonelik checkout'u başlat (ödeme oturumu oluşturur)

POST/store/subscriptions/:id/pause

Aktif aboneliği duraklat

POST/store/subscriptions/:id/resume

Duraklatılmış aboneliği devam ettir

POST/store/subscriptions/:id/change-plan

Farklı plana geç (prorate edilir)

POST/store/subscriptions/:id/cancel

Aboneliği iptal et

Teklif (B2B)

Quote modülünün müşteri tarafı uçları — ISG / B2B teklif talebi gönder, açık teklif kataloğuna bak, üretilen PDF'i indir.

POST/store/quote-requests

Ürün + özel alanlarla teklif talebi gönder

GET/store/quote-requests/:quote_number/pdf

Üretilen teklif PDF'ini indir

GET/store/quote-requests/isg-config

Açık ISG fiyatlandırma yapılandırması (hizmet, baz ücret, lokasyon çarpanları)

GET/store/quote-services

Dropdown seçici için teklif edilebilir hizmetleri listele

Blog

Page modülünden açık blog içeriği. Dil farkındalığı ile, taslak ve zamanlanmış yazılar otomatik filtrelenir.

GET/store/blog-posts

Yayınlanan yazıları listele (dil farkındalığı ile)

GET/store/blog-posts/:slug

Yazı gövdesi + temizlenmiş HTML getir

GET/store/blog-posts/:slug/comments

Yazıya yapılmış yorumları listele

POST/store/blog-posts/:slug/comments

Yeni yorum gönder (moderasyondan geçer)

GET/store/blog-categories

Kategorileri yazı sayılarıyla listele

GET/store/blog-categories/:slug

Tek kategoriyi ve yazılarını getir

GET/store/blog-tags

Etiketleri yazı sayılarıyla listele

GET/store/blog-tags/:slug

Tek etiketi ve yazılarını getir

GET/store/blog-authors/:id

Yazar profili ve yayınladığı yazılar

Sayfa

SEO meta'lı statik CMS sayfaları. Hazır HTML gövdesi içerir.

GET/store/pages

Yayınlanan tüm sayfaları listele

GET/store/pages/:slug

Slug ile statik sayfayı getir

Formlar

Açık form tanımları ve gönderim ucu. Formlar adminde yapılandırılır, her yere gömülebilir.

GET/store/forms/:slug

Form tanımını getir (alanlar, doğrulama, yönlendirme)

GET/store/forms/popup

Aktif pop-up formu getir (varsa)

POST/store/form-submissions

Form gönder (opsiyonel spam token + reCAPTCHA ile)

Medya

Medya varlıklarına açık salt-okunur erişim — storefront'un meta ile görsel render etmesi için.

GET/store/media/:id

Tek varlığı ID ile getir (URL, boyut, alt metin)

E-posta Pazarlama

Liste abonelikleri, çıkış akışları ve müşteri portalının kullandığı açık inbox önizleme ucu.

POST/store/email-subscribe

E-postayı listeye abone et (opsiyonel double opt-in ile)

GET/store/email-unsubscribe

Token ile listeden çık (tek tıklama linki)

POST/store/email-unsubscribe

Çıkışı onayla ve sebep kaydet

POST/store/newsletter

Bülten kayıt (anasayfa / footer widget'ları)

İzleme pikselleri

E-posta açılma + tıklama izleme uçları + genel event ingest. Açılma takibi 1×1 GIF döner; tıklama takibi hedefe 302 yönlendirir.

GET/store/track/open/:campaignId/:subscriberId

E-posta açılmasını piksel ile takip et

GET/store/track/click/:campaignId/:subscriberId

Tıklama takibi yönlendirmesi

POST/store/track/events

Genel analitik event girişi (page_view, add_to_cart, …)

Tema & Menüler

Aktif tema, bölüm tanımları ve çözülmüş menülere salt-okunur erişim — storefront'un dinamik sayfa render'ı için.

GET/store/theme

Aktif tema: token, bölüm, ayar

GET/store/menus/:handle

Bir handle için çözülmüş menü öğeleri (main-menu, footer-menu, …)

Marka

Marka kimliği (logo, renk, tipografi, sosyal bağlantılar, iletişim) — temaların sayfalar arası görsel tutarlılığı için.

GET/store/brand

Aktif mağaza için çözülmüş marka ayarları

Yerelleştirme

Aktif mağaza için mevcut diller ve alan bazlı çeviri override'ları.

GET/store/locales

Aktif dilleri listele (varsayılan + RTL bayrağı ile)

GET/store/translations

Bir kaynak tipi için toplu çeviri override'larını getir

Para Birimi

Storefront'a verilen canlı kur. Kaynaklar: manuel override, ECB ve Frankfurter (otomatik failover).

GET/store/currency-rates

Yapılandırılmış her döviz çifti için aktif kur

GET/store/exchange-rates

Ham kur anlık görüntüsü (`base` parametresi ile)

Metafield'ler

Shopify tarzı tipli özel alanlar; ürün, sipariş, müşteri ve istediğin özel kaynağa eklenebilir.

GET/store/metafields/:resource_type/:resource_id

Belirli bir kaynağa bağlı metafield'leri listele

Yönlendirmeler

Storefront edge'ine verilen aktif 301 / 302 yönlendirmeler. Storefront middleware'i göç haritalarına bunu kullanır.

GET/store/redirects

Tüm aktif yönlendirmeleri listele (kaynak, hedef, statü kodu)

Etkinlikler

Açık etkinlik uçları — etkinlikleri listele, tek etkinliğe git, mevcut biletleri listele, müşterinin kayıtlarını gör.

GET/store/events

Yayınlanan etkinlikleri listele (dil + bölge farkındalığı ile)

GET/store/events/:slug

Tek etkinliği program + konuşmacılarla getir

GET/store/events/:slug/tickets

Bilet varyantlarını ve kalan stoğu listele

GET/store/events/my-registrations

Yetkili müşterinin kayıtlı etkinlikleri

Seyahat — tur & destinasyon

Travel modülü uçları — tur, destinasyon, kategori listele; tur yorumu gönder / oku.

GET/store/tours

Yayınlanan turları listele (destinasyon, süre, fiyat filtreleri)

GET/store/tours/:slug

Tek turu güzergah + kalkışlarla getir

GET/store/tours/:slug/reviews

Tur için onaylı yorumları listele

POST/store/tours/:slug/reviews

Yeni yorum gönder (moderasyondan geçer)

GET/store/destinations

Seyahat destinasyonlarını listele

GET/store/destinations/:slug

Tek destinasyonu ilgili turlarla getir

GET/store/tour-categories

Tur kategorilerini listele

Hizmet Rezervasyonu

Hizmet tabanlı işletmeler için genel rezervasyon ucu — randevu, danışma, atölye saati.

GET/store/service-bookings

Bir hizmet için rezerve edilebilir saatleri listele

POST/store/service-bookings

Yeni rezervasyon oluştur

AI Asistan

Güçlü AI modellerini bağla — kendi OpenAI, Gemini, DeepL veya ElevenLabs anahtarını getir ya da kullandıkça öde kredileri kullan. Asistan 24 yetenek paketiyle (skill) gelir — mağaza kurulumu, e-ticaret editörü, tema editörü, pazarlama yöneticisi, SEO denetçisi, görsel üretici ve daha fazlası. Tam yetenek kataloğu /ai-skills'te. Üç entegrasyon yolu: (1) /admin/ai/* altındaki admin-yetkili proxy'ler ürün içi AI özellikleri için, (2) /v1/* altındaki doğrudan nuvi-agent API sunucu-sunucu işler için (Bearer NUVI_AGENT_API_KEY, asla tarayıcıya açma), (3) çoklu-aksiyon onay akışları için SSE üzerinden gerçek zamanlı streaming varyant.

POST/admin/ai/chat

Tek-tur sohbet — mesaj + sessionId gönder, yanıt al. Intent'i otomatik algılar, doğru skill'i çalıştırır.

Örnek istek
curl -X POST https://usenuvi.com/api/admin/ai/chat \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"message":"Bu hafta hangi ürünler en çok satıldı?","session_id":"sess_..."}'
POST/admin/ai/chat/stream

SSE streaming sohbet — artımlı tokenlar + istemcinin onaylaması/reddetmesi gereken aksiyon planı eventleri yayar

POST/admin/ai/chat/stream/:streamId/approve

Bekleyen çoklu-aksiyon planını onayla (yürütmeye geçer)

POST/admin/ai/chat/stream/:streamId/reject

Bekleyen planı reddet (yürütme atlanır, yan etki yok)

GET/admin/ai/skills

Mevcut 24 skill'i kategori, örnek ve ikon adı ile listele

GET/admin/ai/skills-config

Mağaza başına skill aktivasyonu (operatörün bu tenant için açtığı skill'ler)

GET/admin/ai/store-context

Asistanın kullandığı mağaza-farkındalıklı context (katalog boyutu, kurlar, locale, yapılandırılmış modüller)

POST/admin/ai/translate

Tek seferlik LLM çeviri — input string + hedef locale, çevrilmiş string döner. Admin'in 11 dil i18n pipeline'ı kullanır.

Örnek istek
curl -X POST https://usenuvi.com/api/admin/ai/translate \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"text":"Save changes","target_locale":"de"}'
POST/admin/ai/voice/blog

Blog yazısı için AI seslendirme üret (tamamlandığında audio URL döner)

POST/admin/ai/voice/synthesize-chunk

Anlık tek parça sentez (artımlı editör oynatması sırasında)

POST/admin/ai/marketing/social/draft

Brief'ten AI sosyal post (caption + hashtag) taslağı üretir

POST/admin/ai/marketing/social/publish

Bir taslağı bağlı sosyal hesaba yayınla (Facebook, Instagram, ...)

POST/admin/ai/marketing/social/schedule

Bir taslağı ileri tarihli yayınlamak için planla

GET/admin/ai/marketing/metrics/dashboard

Çapraz kanal kampanya metrikleri (Google Ads, Meta) — harcama, gösterim, dönüşüm

POST/v1/chat

Doğrudan nuvi-agent sohbet — NUVI_AGENT_API_KEY ile Bearer auth (yalnızca sunucu)

POST/v1/chat/stream

SSE stream varyantı — çoklu aksiyon onay akış eventleri

POST/v1/extract-actions

Doğal dilden yapılandırılmış aksiyonları çıkar (yürütme yok, sadece plan)

GET/v1/skills

24 skill'in hepsini metadata ile listele (id, kategori, model_tier, ikon)

GET/v1/setup-status

Tenant onboarding durumu — hangi skill'ler yapılandırıldı, hangileri credentials bekliyor

Webhook (yol haritası)

Dış event gönderimi yakın vadeli yol haritasında. Bugün, yerleşik workflow motoru üzerinden iç event'lere abone olabilirsin. Aşağıdaki şekil planlanan imzalı payload formatı — HMAC-SHA256 (`x-nuvi-signature` header).

POSTorder.placed

Sepet siparişe dönüştüğünde tetiklenir

POSTorder.payment_captured

Ödeme tahsil edildiğinde tetiklenir

POSTorder.fulfilment_shipped

Hazırlama kargolandığında tetiklenir

POSTcustomer.created

Yeni müşteri kaydında tetiklenir

POSTsubscription.renewed

Her başarılı yenileme döngüsünde tetiklenir

POSTquote.submitted

Müşteri teklif talebi gönderdiğinde tetiklenir

Hatalar

Tüm hatalar `code`, `message`, `type` alanları ile JSON olarak döner. HTTP statü standartlara uyar: 400 doğrulama, 401 yetki, 403 izin, 404 bulunamadı, 429 rate-limit, 5xx sunucu.

Hata gövdesi
{
  "type": "validation_error",
  "code": "missing_field",
  "message": "Field 'email' is required."
}

Rate limit

Storefront çağrıları: IP başına 60 req/sn. Admin çağrıları: token başına 30 req/sn. Soft-fail yanıtları `Retry-After` ve `X-RateLimit-Remaining` header'larını içerir — geri çekil ve tekrar dene.

Yanıt header'ları
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714425600
Retry-After: 30

Suistimal koruması

Açık POST uçları (form gönderimi, blog yorumları, teklif talebi, bülten kaydı) storefront tarafından verilen anti-spam token gerektirir ve reCAPTCHA Enterprise'tan geçer. Geçerli token'ı olmayan çağrılar 403 döner. Admin JWT'ni asla istemci kodda paylaşma — sunucuda tut, kendi backend'inden proxy yap.

API ile geliştir

Panelden publishable API anahtarı al, beş dakikada entegrasyona başla. JS, Python ve PHP için native SDK'lar yakında — REST bugün her yerde çalışır.

API anahtarı alBir geliştiriciyle konuş