SDK'lar ve örnek kod
Go, Node.js, PHP ve React için ClickFix SDK kullanım örnekleri; kimlik doğrulama, tekrar deneme, sayfalama, webhook imzası ve SDK'sız istekler.
ClickFix'in Go, Node.js ve PHP için sunucu SDK'ları ile React için arayüzsüz bir widget istemcisi vardır. SDK'lar kimlik doğrulama, sınırlı tekrar deneme (Retry-After dahil), sayfalama ve webhook imza doğrulaması sağlar.
Paketler
npm install @getclickfix/node (0.1.0, Node 22+), npm install @getclickfix/react-widget (0.1.0, React 18+), composer require clickfix/sdk
(0.1.0, PHP 8.1+) ve go get github.com/ClickSolveMainTR/clickfix-sdks/go@v0.1.0. Baştan sona kurulum
sırası ve her adımda doğrulanmış örnekler: Entegrasyon
kılavuzu. Laravel 10-13 için composer require clickfix/laravel (0.1.0): Laravel paketi.
Aşağıdaki SDK'sız örnekler aynı işlemleri doğrudan HTTP ile
yapar; API başvurusundaki her uç noktanın
yanında curl, JavaScript, Python ve Go için hazır istek örnekleri de bulunur.
Temel adres olarak https://api.getclickfix.com verin (sonuna /v1 eklemeyin). API anahtarları yalnızca sunucuda kalmalıdır; tarayıcı koduna koymayın. Anahtar oluşturma ve kapsamlar: API.
İstemci oluşturma ve istek gönderme
Yazma işlemlerinde işlemi tanımlayan sabit bir Idempotency-Key verin (ör. sipariş numarası) ve tekrar denemelerde aynı değeri gönderin.
import { createClient } from "@getclickfix/node";
const client = createClient({
baseURL: "https://api.getclickfix.com",
apiKey: process.env.CLICKFIX_API_KEY!,
});
const created = await client.request(
"/v1/public-api/conversations",
"post",
{
contact_uuid: contactUUID,
inbox_uuid: inboxUUID,
subject: "Teslimat sorusu",
},
{
idempotencyKey: "siparis-1042-destek",
signal: AbortSignal.timeout(30_000),
},
);Node.js istemcisi hata yanıtlarında durum, kod, istek kimliği ve ayrıntıları taşıyan bir APIError fırlatır. GET istekleri ve anahtarlı yazmalar varsayılan olarak en fazla üç kez denenir (üstel bekleme, sınırlı Retry-After); anahtarsız yazmalar tekrar denenmez. Go istemcisi 30 saniyelik HTTP zaman aşımı ve aynı tekrar deneme kuralını ekler.
API tamamlanmış yazma yanıtlarını (hatalar dahil) saklar: aynı anahtarla tekrar denemek kayıtlı bir hatayı başarıya çeviremez. Düzeltilmiş girdi için yeni bir anahtar kullanın.
Sayfalama
import { paginate } from "@getclickfix/node";
for await (const contact of paginate(async (limit, offset) => {
const envelope = await client.request(
"/v1/public-api/contacts",
"get",
undefined,
{
query: { limit, offset },
},
);
// envelope.data'yı kendi şemanızla doğrulayıp {items, total, limit, offset} döndürün.
return validateContactPage(envelope.data);
})) {
await consume(contact);
}Ofset sayfalama anlık görüntüler içindir; eşzamanlı eklemeler sayfaları kaydırabilir. Eşitleme yaparken UUID'leri tekilleştirin; artımlı eşitleme için tetikleyici imlecini kullanın.
Webhook imzası ve kimlik özeti
import { identityHash, verifyWebhook } from "@getclickfix/node";
const valid = verifyWebhook(
secret,
headers.timestamp,
headers.signature,
rawBody,
);
// Web widget'ında oturum açmış kullanıcı için user_hash
const userHash = identityHash(identitySecret, authenticatedUser.id);İmzayı JSON'u ayrıştırmadan önce, ham gövde üzerinde doğrulayın ve yan etkilerden önce ClickFix-Webhook-Id değerini kaydedip tekilleştirin. SDK'sız doğrulama örnekleri (Node.js, Python, Go): Webhook'lar.
React widget istemcisi
Hazır mesajlaşma arayüzünü (balon, ana sayfa, yardım merkezi) kendi düğmenizle yönetmek için tipli hook'lar:
"use client";
import { useMemo } from "react";
import { useClickFix, useClickFixEvent } from "@getclickfix/react-widget";
export function Support({ consent }: { consent: boolean }) {
const options = useMemo(
() =>
consent
? {
appOrigin: "https://getclickfix.com",
widgetId: "WIDGET_ID",
hideLauncher: true,
}
: null, // null, onay verilene kadar yüklemeyi erteler
[consent],
);
const { ready, unread, open, sdk } = useClickFix(options);
useClickFixEvent("conversation:ended", (e) => console.log(e.status));
return (
<button aria-expanded={open} disabled={!ready} onClick={() => sdk.toggle()}>
Destek {unread || ""}
</button>
);
}Arayüzsüz istemcide konuşmaları ve mesajları kendiniz çizersiniz:
await client.identify({ user_id: user.id, user_hash: serverProvidedHmac });
const { items } = await client.conversations();
await client.createConversation({
text: "Merhaba",
client_id: crypto.randomUUID(),
});
await client.sendMessage(
conversationUUID,
{ text: "Fotoğraf", client_id: stableMessageUUID },
file,
);
await client.markRead(conversationUUID);user_hash sunucunuzda üretilir; kimlik anahtarını tarayıcıya göndermeyin. Widget komutları ve olayları: Web widget.
SDK'sız istekler
curl -X POST "https://api.getclickfix.com/v1/public-api/conversations/KONUSMA_UUID/messages" \
-H "Authorization: Bearer $CLICKFIX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: siparis-1042-not" \
-d '{ "content": "Sipariş kargoya verildi.", "private": true }'429 RATE_LIMITED yanıtında Retry-After süresi kadar bekleyip aynı Idempotency-Key ile tekrar deneyin; 400, 401 ve 403 hatalarını tekrar denemeyin.