shopier-pat-api

Shopier'in yeni PAT tabanlı REST API'si için Node.js / TypeScript SDK.

⚠️ Eski api_pay4.php sistemi artık çalışmıyor. Bu paket tamamen yeni api.shopier.com/v1 üzerine inşa edilmiştir.

Özellikler

• Sıfır bağımlılık — yalnızca Node.js built-in modülleri (node:crypto, node:fetch)
• PAT ile kimlik doğrulama — eski API key/secret sistemine gerek yok
• Otomatik ürün akışı — ödeme için ürün oluştur, ödeme gelince otomatik sil
• fastPay modu — müşteriyi ürün sayfasını atlayıp direkt ödeme formuna gönder
• Otomatik sipariş kapatma — fulfillOrder() ile ödeme sonrası siparişi kapat
• Webhook doğrulama — HMAC-SHA256 + timing-safe imza kontrolü
• Express middleware — hazır expressMiddleware() ile tek satır entegrasyon
• Tam TypeScript desteği — tüm modeller ve hata sınıfları tip-güvenli
• ESM + CommonJS — her iki format desteklenir

Nasıl Çalışır?

1. flow.create()       →  Shopier'de geçici ürün oluşturulur
2. paymentUrl / fastPay →  Müşteriye link gönderilir veya direkt ödeme sayfasına yönlendirilir
3. Müşteri ödeme yapar  →  Shopier sunucuna order.created webhook'u atar
4. expressMiddleware()  →  İmza doğrulanır, sipariş bilgileri alınır, iş mantığın çalışır
5. Ürün otomatik silinir + sipariş otomatik kapatılır  ✓

Kurulum

npm install shopier-pat-api

Kurulum Adımları

1. PAT Oluştur

1. shopier.com'a giriş yap
2. Hesap → Hesap Güvenliği → 2FA'yı etkinleştir (zorunlu)
3. Hesap → Kişisel Erişim Anahtarı → Yeni PAT oluştur
4. Token'ı kopyala — bir daha gösterilmez!

2. Webhook Token Al

Webhook aboneliği oluştururken dönen token değerini saklaman gerekiyor. Bunu kolayca yapmak için paketteki setup-webhook.mjs scriptini kullanabilirsin:

node setup-webhook.mjs https://siteniniz.com/shopier/webhook
# → SHOPIER_WEBHOOK_TOKEN .env dosyasına otomatik kaydedilir

3. .env Dosyası

SHOPIER_PAT=pat_buraya
SHOPIER_WEBHOOK_TOKEN=webhook_token_buraya

Hızlı Başlangıç (Express)

import 'dotenv/config';
import express from 'express';
import { ShopierClient, ShopierWebhook, ShopierPaymentFlow } from 'shopier-pat-api';

const app = express();

const client  = new ShopierClient({ pat: process.env.SHOPIER_PAT! });
const webhook = new ShopierWebhook(process.env.SHOPIER_WEBHOOK_TOKEN!);
const flow    = new ShopierPaymentFlow(client, webhook);

// ── Ödeme linki oluştur ───────────────────────────────────────────────────────
app.get('/odeme-olustur', async (req, res) => {
  const payment = await flow.create({
    title: 'Premium Üyelik',
    price: 149.90,
    currency: 'TRY',
    imageUrl: 'https://siteniniz.com/logo.png',
  });

  // Müşteriye sadece link döndür
  res.json({ link: payment.paymentUrl });
  // → https://www.shopier.com/123456
});

// ── fastPay: Direkt ödeme formuna yönlendir (ürün sayfasını atla) ─────────────
app.get('/hizli-odeme', async (req, res) => {
  const payment = await flow.create({
    title: 'Premium Üyelik',
    price: 149.90,
    fastPay: true,         // ← ürün sayfası gösterilmez, direkt checkout açılır
  });

  res.send(payment.fastPayHtml);
});

// ── Webhook: Ödeme bildirimini al ─────────────────────────────────────────────
app.post(
  '/shopier/webhook',
  express.raw({ type: '*/*' }),
  flow.expressMiddleware(async ({ order, productId }) => {
    // Ödeme doğrulandı, ürün silindi — iş mantığın buraya:
    console.log('Ödeme alındı! Sipariş:', order.id, '| Tutar:', order.totals.total, order.currency);
    console.log('Alıcı:', order.shippingInfo.firstName, order.shippingInfo.email);

    // Siparişi kapat (Shopier panelinde "Teslim Edildi" olarak görünür)
    await client.fulfillOrder(order.id, {
      fulfillments: {
        productType: 'digital',
        note: 'Siparişiniz teslim edildi, teşekkürler!',
      },
    });

    // Örnek iş mantıkları:
    // await db.activateLicense(order.id, order.shippingInfo.email);
    // await sendEmail(order.shippingInfo.email, 'Lisans anahtarınız: ABC-123');
  }),
);

app.listen(3000);

API Referansı

new ShopierClient(config)

| Parametre | Tip | Zorunlu | Açıklama | |-----------|-----|---------|----------| | pat | string | ✅ | Shopier Kişisel Erişim Anahtarı | | baseUrl | string | — | Varsayılan: https://api.shopier.com/v1 | | timeoutMs | number | — | İstek zaman aşımı (ms). Varsayılan: 15000 |

Ürünler

| Method | Açıklama | |--------|----------| | createProduct(input) | Yeni ürün oluşturur | | getProduct(id) | Tek ürünü getirir | | listProducts(params?) | Ürün listesi | | deleteProduct(id) | Ürünü siler |

Siparişler

| Method | Açıklama | |--------|----------| | getOrder(id) | Siparişi getirir | | listOrders(params?) | Sipariş listesi | | fulfillOrder(id, input) | Siparişi kapatır (teslim edildi) |

Webhooks

| Method | Açıklama | |--------|----------| | createWebhook(event, url) | Abonelik oluşturur — dönen token'ı sakla! | | listWebhooks() | Abonelikleri listeler | | deleteWebhook(id) | Aboneliği siler |

new ShopierWebhook(token)

Webhook aboneliği oluştururken dönen token değerini alır.

| Method | Açıklama | |--------|----------| | verify(rawBody, signature) | İmzayı doğrular, geçersizse WebhookSignatureError fırlatır | | parse(rawBody, headers) | Doğrular + parse eder, WebhookPayload döner | | middleware(handler) | Express middleware üretir |

new ShopierPaymentFlow(client, webhook)

| Method | Açıklama | |--------|----------| | create(options) | Ürün oluşturur, { productId, paymentUrl, fastPayHtml?, product } döner | | handleWebhookPayload(rawBody, headers, onPayment, autoDelete?) | Ham webhook işler | | expressMiddleware(onPayment, autoDelete?) | Express middleware döner |

create() Seçenekleri

| Parametre | Tip | Zorunlu | Açıklama | |-----------|-----|---------|----------| | title | string | ✅ | Ürün başlığı | | price | number | ✅ | Tutar (ör: 149.90) | | currency | CurrencyCode | — | TRY / USD / EUR. Varsayılan: TRY | | description | string | — | Ürün açıklaması | | imageUrl | string | — | Kapak görseli (HTTPS, jpg/png/bmp) | | customNote | string | — | Alıcıdan özel bilgi iste (ör: "Kullanıcı adınız?") | | fastPay | boolean | — | true → direkt ödeme formuna yönlendir, false → sadece URL döner |

fulfillOrder() Seçenekleri

// Dijital ürün için
await client.fulfillOrder(orderId, {
  fulfillments: {
    productType: 'digital',
    note: 'İndirme linkiniz: https://...',   // alıcıya gösterilir
  },
});

// Fiziksel ürün için
await client.fulfillOrder(orderId, {
  fulfillments: {
    productType: 'physical',
    shippingCompany: 'yurtici',
    trackingNumber: '1234567890',
  },
});

Webhook Olayları

| Olay | Tetiklenme | |------|------------| | order.created | Ödeme tamamlandığında | | order.fulfilled | Sipariş kapatıldığında | | order.addressUpdated | Teslimat adresi değiştiğinde | | product.created | Ürün oluşturulduğunda | | product.updated | Ürün güncellendiğinde | | refund.requested | İade talebi geldiğinde | | refund.updated | İade durumu değiştiğinde |

Gelişmiş Kullanım

Birden fazla webhook olayı dinlemek

const webhook = new ShopierWebhook(process.env.SHOPIER_WEBHOOK_TOKEN!);

app.post('/shopier/webhook', express.raw({ type: '*/*' }), webhook.middleware(async (payload) => {
  switch (payload.event) {
    case 'order.created':
      const order = payload.body as Order;
      await activateLicense(order);
      break;
    case 'refund.requested':
      await cancelLicense(payload.body);
      break;
  }
}));

Manuel ürün oluşturma (tam kontrol)

const product = await client.createProduct({
  title: 'Yazılım Lisansı',
  type: 'digital',
  shippingPayer: 'sellerPays',
  priceData: { currency: 'TRY', price: '299.00' },
  media: [{ type: 'image', url: 'https://siteniniz.com/cover.jpg', placement: 1 }],
  customNote: 'Lisans için e-posta adresinizi yazın',
  stockQuantity: 1,
});

console.log('Ödeme linki:', product.url);
await client.deleteProduct(product.id); // ödeme sonrası temizle

Hata Sınıfları

import { ShopierError, ApiError, WebhookSignatureError, ConfigError } from 'shopier-pat-api';

try {
  await client.getOrder('123');
} catch (err) {
  if (err instanceof ApiError) {
    console.error('API Hatası:', err.message, '| HTTP:', err.statusCode);
  }
  if (err instanceof WebhookSignatureError) {
    console.error('Sahte webhook isteği reddedildi');
  }
}

| Sınıf | Ne Zaman | |-------|----------| | ConfigError | PAT veya webhook token eksik/boş | | ApiError | Shopier API HTTP hatası döndürdüğünde | | WebhookSignatureError | Webhook imzası geçersiz olduğunda |

Güvenlik

• SHOPIER_PAT ve SHOPIER_WEBHOOK_TOKEN değerlerini asla frontend koduna veya Git geçmişine ekleme
• .env dosyasını .gitignore'a ekle
• Webhook endpoint'in HTTPS üzerinde çalışmalı
• fulfillOrder() çağrısından önce verifyCallback() / expressMiddleware() ile imzayı doğrula

Lisans

MIT