Örnek Uygulama: Logo İşbaşı

{
  "name": "Logo İşbaşı",
  "slug": "isbasi",
  "hosting": "tecof",
  "embedded": true,
  "scopes": ["orders:read", "customers:read", "products:read"],
  "webhooks": {
    "path": "/api/webhooks",
    "events": ["order.paid", "order.cancelled", "order.refunded"]
  },
  "actions": [
    {
      "key": "create-invoice", "type": "iframe", "placement": "order.detail",
      "title": { "tr": "İşbaşı'nda fatura kes", "en": "Create İşbaşı invoice" },
      "path": "/actions/create-invoice", "presentation": "modal"
    },
    {
      "key": "bulk-invoice", "type": "api", "placement": "order.list",
      "title": { "tr": "Seçilenleri faturala", "en": "Invoice selected" },
      "path": "/api/actions/bulk-invoice",
      "confirm": { "tr": "Seçili siparişler için fatura kesilsin mi?", "en": "Create invoices for selected orders?" }
    }
  ],
  "navigation": [
    { "label": { "tr": "Faturalar", "en": "Invoices" }, "path": "/invoices" }
  ],
  "settings": [
    { "key": "username", "label": { "tr": "İşbaşı kullanıcı adı", "en": "İşbaşı username" }, "type": "text", "required": true },
    { "key": "password", "label": { "tr": "İşbaşı parolası", "en": "İşbaşı password" }, "type": "secret", "required": true },
    { "key": "apiKey", "label": { "tr": "İşbaşı API anahtarı", "en": "İşbaşı API key" }, "type": "secret", "required": true },
    { "key": "autoInvoice", "label": { "tr": "Ödenen siparişleri otomatik faturala", "en": "Auto-invoice paid orders" }, "type": "boolean" },
    { "key": "issueInvoices", "label": { "tr": "Faturayı taslak değil kesilmiş olarak oluştur", "en": "Issue invoices instead of drafts" }, "type": "boolean" },
    { "key": "defaultVatRate", "label": { "tr": "Varsayılan KDV oranı (%)", "en": "Default VAT rate (%)" }, "type": "number" }
  ],
  "appEvents": {
    "publishes": [
      { "name": "invoice.created", "description": { "tr": "Fatura oluşturuldu", "en": "Invoice created" } }
    ],
    "subscribes": ["app.kargo.shipment.created"]
  },
  "plans": [
    {
      "key": "standart", "name": { "tr": "Standart", "en": "Standard" },
      "description": { "tr": "Sınırsız otomatik fatura", "en": "Unlimited automatic invoices" },
      "price": 199, "currency": "TRY", "interval": "month", "trialDays": 14,
      "features": [{ "tr": "Sınırsız fatura", "en": "Unlimited invoices" }]
    }
  ],
  "listing": {
    "shortDescription": { "tr": "Siparişlerinizi Logo İşbaşı'nda otomatik faturalayın", "en": "Automatically invoice orders in Logo İşbaşı" },
    "description": { "tr": "…", "en": "…" },
    "category": "accounting",
    "supportEmail": "destek@ornek.com",
    "privacyUrl": "https://ornek.com/gizlilik"
  }
}

// lib/invoice.ts
import { tecof } from "@/lib/tecof";
import { createIsbasiInvoice } from "@/lib/isbasi"; // uygulamaya özgü İşbaşı istemcisi

export async function invoiceOrder(installationId: string, orderId: string) {
  const api = tecof.client(installationId);

  // 1) Idempotency: siparişte fatura numarası varsa tekrar kesme
  const existing = await api.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });
  if (existing.some((m: { key: string }) => m.key === "invoiceNumber")) {
    return { status: "skipped" as const };
  }

  // 2) Siparişin güncel hâli
  const order = await api.orders.get(orderId);
  if (order.currency !== "TRY") {
    return { status: "unsupported-currency" as const }; // v1: yalnız TRY
  }

  // 3) Ayarlar ve Vault
  const { settings } = await api.settings.get();
  const [{ value: password }, { value: apiKey }] = await Promise.all([
    api.secrets.get("password"),
    api.secrets.get("apiKey"),
  ]);
  const defaultVatRate = Number(settings.defaultVatRate ?? 20);

  // 4) İşbaşı'nda fatura
  const invoice = await createIsbasiInvoice(
    { username: String(settings.username), password, apiKey },
    {
      issue: settings.issueInvoices === true, // false → taslak
      buyer: order.billingAddress,            // identityNumber: TCKN/VKN
      lines: order.lineItems.map((li) => ({
        name: li.variantTitle ? `${li.name} (${li.variantTitle})` : li.name,
        sku: li.sku,
        quantity: li.quantity,
        unitPrice: li.unitPrice,
        vatRate: li.taxRate ?? defaultVatRate, // null = eski sipariş → mağaza varsayılanı
        taxIncluded: li.taxIncluded,
      })),
      shipping: order.shippingLines,
      discounts: order.discountLines,
    },
  );

  // 5) Fatura numarasını siparişe yaz (panelde görünür, diğer uygulamalarla paylaşılır)
  await api.metafields.set({
    ownerType: "order",
    ownerId: order.id,
    key: "invoiceNumber",
    type: "string",
    value: invoice.number,
    visibility: "shared",
    panel: { label: { tr: "İşbaşı fatura no", en: "İşbaşı invoice no" }, show: true },
  });

  // 6) Olayı yayınla
  await api.events.publish("invoice.created", {
    orderId: order.id,
    orderNumber: order.orderNumber,
    invoiceNumber: invoice.number,
    issued: settings.issueInvoices === true,
  });

  return { status: "created" as const, invoiceNumber: invoice.number };
}

// app/api/webhooks/route.ts
import { createWebhookHandler } from "@tecof/app-sdk";
import { tecof } from "@/lib/tecof";
import { invoiceOrder } from "@/lib/invoice";

export const POST = createWebhookHandler({
  app: tecof,
  handlers: {
    "order.paid": async (event) => {
      const { settings } = await tecof.client(event.installationId).settings.get();
      if (settings.autoInvoice === true) {
        await invoiceOrder(event.installationId, String(event.data.orderId));
      }
    },
    // v1: fatura otomatik iptal edilmez — iptal/iade belgesi İşbaşı'nda yönetilir
    "order.cancelled": async () => {},
    "order.refunded": async () => {},
  },
});