API ve webhook'lar — Craft'ı CRM'inize veya web sitenize bağlayın

Craft'ı anahtarlı isteklerle nasıl kontrol eder ve yeni kişiler, düğme tıklamaları, ödemeler ve gönderiler hakkındaki olayları kendi sunucunuzda nasıl alırsınız.

Craft'ı CRM'inize, bir müşterinin web sitesine veya kendi herhangi bir hizmetinize bağlayabilirsiniz. MCP bağlayıcısının yapabildiği her şey anahtarlı düz bir HTTPS isteği olarak mevcuttur: huniler, kişiler, toplu mesajlar, gönderiler, karuseller, görseller. Webhook'lar ters yönde çalışır: yeni bir kişi göründüğünde, biri bir düğmeye tıkladığında, bir huni hedefine ulaştığında, ödeme yaptığında veya bir gönderi yayına girdiğinde Craft sunucunuza bir olay gönderir.

Nasıl çalışır#

• Craft'ta bir anahtar oluşturur ve ne yapabileceğini seçersiniz: yalnızca okuma veya huniler, kişiler, toplu mesajlar, gönderiler vb. ile çalışma.
• Sunucunuz, başlıkta anahtarla https://craftopen.space/api/v1/tools/<method> adresine bir istek gönderir. Yöntem parametreleri JSON istek gövdesinde gider.
• Craft yöntemi hesabınızda çalıştırır — tıpkı siz web sitesinde yapmış veya MCP bağlayıcısı üzerinden yapay zekânızdan istemiş gibi, aynı kontroller ve limitlerle.
• Olaylar için bir webhook eklersiniz — sunucunuzun adresi. Craft oraya imzalı bir istek gönderir ve sunucunuz yanıt vermezse yeniden dener.

Neye ihtiyacınız var#

• Herhangi bir tarife: anahtarlar ve webhook'lar ücretsiz dahil her tarifede oluşturulabilir.
• HTTPS istekleri gönderip alabilen bir sunucu veya hizmet: kendi kodunuz, Make, n8n, Zapier veya gelen webhook'ları olan bir CRM.

Adım 1. Bir anahtar oluşturun#

Profil menüsü → API ve webhook'lar (API & webhooks) (veya Ayarlar → API ve webhook'lar) → Yeni anahtar.

1. Anahtara sonra tanıyacağınız bir ad verin: "HubSpot", "Müşteri web sitesi".
2. Anahtarın ne yapabileceğini seçin. Yeni bir anahtar varsayılan olarak yalnızca okuyabilir. Diğer her şey onay kutularıyla açılır: huniler, kişiler, toplu mesajlar, gönderiler, içerik, İçerik Fabrikası, hesaplar. "Her şey", sonradan eklenenler dahil tüm yetenekleri açar.
3. Anahtarın gönderileri ve toplu mesajları nasıl yayınlayacağını seçin: - Yalnızca taslaklar — her şey taslak olarak kaydedilir ve siz Craft'ta kendiniz gönderirsiniz; - Zamanlanmış — en erken 10 dakika sonra, böylece iptal etmek için zaman olur; - Anında — istek anında yayınlar ve gönderir.
4. Görsel harcamaları için günlük limiti ve anahtarın bir bottan günde kaç toplu mesaj gönderebileceğini ayarlayın.
5. Anahtar oluştur'a tıklayın ve hemen kopyalayın.

Bir anahtarın izinlerini ve ayarlarını istediğiniz zaman "Ayarlar" ile değiştirebilirsiniz — değişiklikler bir dakika içinde etkili olur. "İptal et" anahtarı hemen kapatır.

Adım 2. İlk isteğiniz#

curl -X POST https://craftopen.space/api/v1/tools/list_funnels \
  -H "Authorization: Bearer craft_your_key" \
  -H "Content-Type: application/json" \
  -d '{}'

Başarılı bir yanıt her zaman böyle görünür — verinin kendisi data içindedir:

{"ok": true, "data": {"funnels": [ ... ]}}

Bir şey yanlışsa "ok": false ve açık bir neden alırsınız:

{"ok": false, "error": {"code": "funnel_not_found", "message": "Воронка не найдена."}}

Mevcut yöntemler#

Tüm yöntemler ve açıklamalı parametreleri:

• Craft'ta: anahtarınızla GET https://craftopen.space/api/v1/tools — liste her yöntemin hangi izni gerektirdiğini ve bu anahtarın onu çağırıp çağıramayacağını söyler;
• bir OpenAPI açıklaması: craftopen.space/api/v1/openapi.json — Postman, Insomnia ve istemci üreteçleri onu anlar.

Yöntemler MCP bağlayıcısınınkilerle aynıdır. En yaygın olanlar:

GET https://craftopen.space/api/v1/me hangi anahtarı kullandığınızı, izinlerini ve bugün kaç istek kaldığını gösterir.

Çift kayıt olmadan yeniden deneme#

Bir istek koptuysa ve geçip geçmediğini bilmiyorsanız aynı Idempotency-Key başlığıyla yeniden gönderin. Gönderi iki kez çıkmaz ve bir görsel iki kez ücretlendirilmez.

curl -X POST https://craftopen.space/api/v1/tools/schedule_post \
  -H "Authorization: Bearer craft_your_key" \
  -H "Idempotency-Key: post-2026-09-27-lime-1" \
  -H "Content-Type: application/json" \
  -d '{"account_ids": ["..."], "confirm_usernames": ["@lime_agency"],
       "carousel_id": "...", "caption": "Post text",
       "scheduled_at": "2026-09-27T19:00:00+03:00"}'

Hatalar ve ne yapmalı#

Limitler#

• Hesap başına dakikada 60 istek ve günde 10.000 — tüm anahtarlar genelinde. Gün Moskova saatiyle (UTC+3) sayılır. Daha fazlası mı gerekiyor? Destek ekibine yazın; limit tarifenizi değiştirmeden artırılır.
• Webhook'lar limite sayılmaz.
• Görseller web sitesindeki fiyatlarla credits harcar ve asla anahtar için belirlediğiniz günlük limiti aşmaz.
• Toplu mesajlar: bot başına günde seçilen sayıdan fazla değil. Göndermeden önce send_broadcast_test ile aynı metnin kendinize test gönderimi zorunludur.

Webhook'lar#

API ve webhook'lar → Webhook ekle: sunucu adresinizi girin (yalnızca https://) ve olayları seçin. Oluşturduktan hemen sonra Craft imzalama sırrını gösterir — kaydedin, bir daha gösterilmez ("Yeni sır" ile yenisini oluşturabilirsiniz).

Test, bir ping olayı gönderir ve sunucunuzun ne yanıt verdiğini gösterir. Günlük son teslimatları listeler: ne gönderildiği, ulaşıp ulaşmadığı, yanıt ve bir "Yeniden dene" düğmesi.

Olaylar#

Ajan olayları platform (instagram veya telegram), account_id (Instagram hesabı veya bot), contact_id ve bir zaman damgası taşır, böylece ajanın konuşma geçmişini kendi CRM'inizde veya hizmetinizde tutabilirsiniz.

Örnek istek gövdesi:

{
  "id": "6f1c…",
  "type": "contact.created",
  "created_at": "2026-09-26T09:04:11+00:00",
  "data": {
    "platform": "telegram",
    "contact_id": "…",
    "bot_username": "shop_bot",
    "first_name": "Anna",
    "username": "anna",
    "source": {"type": "link", "ref": "promo"}
  }
}

Olay id'si yeniden denemeler boyunca aynı kalır — çift kayıtları atmak için kullanın.

Bir isteğin Craft'tan geldiğini doğrulama#

Her isteğin bir Craft-Signature: t=<zaman>,v1=<imza> başlığı vardır. İmza, sırrınızla <zaman>.<istek gövdesi> dizesinin HMAC-SHA256'sıdır. Hesaplayın ve karşılaştırın:

import hmac, hashlib, time

def craft_signature_ok(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:   # older than 5 minutes — reject
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

const crypto = require("crypto");

function craftSignatureOk(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Yeniden denemeler#

Craft bir yanıt için 10 saniyeye kadar bekler. Herhangi bir 2xx yanıtı teslim edilmiş sayılır. Aksi halde Craft 1 dakika, 5 dakika, 30 dakika, 2, 6, 12 ve 24 saat sonra yeniden dener — toplam 8 deneme, ardından olay "başarısız" olarak işaretlenir (günlükten yeniden gönderebilirsiniz).

Hızlı yanıt verin ve yavaş işi yanıttan sonra yapın: sunucunuz 10 saniyeden uzun sürerse Craft denemeyi başarısız sayar ve olayı yeniden gönderir.

Kendi kanalınız: yapay zekâ ajanı yanıtları#

Müşteriler size Craft'ın bağlı olmadığı yerlerde yazıyorsa (kendi mesajlaşma uygulamanız, web sitesi sohbeti, CRM), yapay zekâ ajanı orada da yanıt verebilir. Sisteminiz müşterinin mesajını gönderir — Craft ajanın yanıtını döndürür. Sisteminiz onu müşteriye iletir.

curl -X POST https://craftopen.space/api/v1/agent/reply \
  -H "Authorization: Bearer craft_…" -H "Content-Type: application/json" \
  -d '{"ig_user_id": "1784…", "contact_id": "client-42", "text": "How much is JET+?", "name": "Ivan"}'

• Kimin ajanı yanıt verir — ajanı kurulu bir Instagram hesabının ig_user_id'si veya bir Telegram botunun tg_bot_id'si. Onun kuralları, bilgi tabanı, modeli ve devir ayarları kullanılır.
• contact_id — sabit müşteri kimliğiniz; ajan konuşmayı bununla hatırlar. name — isteğe bağlı, personele devir için.
• Yanıt: reply — müşteri için metin, handed_over — ajan müşteriyi personele devretti (potansiyel müşteri Instagram potansiyel müşterilerinin gittiği yere gider), paused — ajan personel onu geri verene kadar sessiz kalır, credits_charged — harcanan credits.
• Yanıtlar, Instagram'daki gibi credits tutar. Credits biterse no_credits hatası alırsınız.
• agent.message_received, agent.replied ve agent.handed_over olayları bu kanal için de tetiklenir.

Henüz mevcut değil#

• Hazır istemci kütüphaneleri — OpenAPI açıklamasını kullanın.
• Anahtar ve webhook'ları API'nin kendisiyle oluşturma — yalnızca API ve webhook'lar sayfasında.
• Üçüncü taraf uygulamalar için "Craft ile giriş yap": bir anahtar yalnızca kendi hesabınıza erişim verir.