Genel bakış
Veklam API'si Beta aşamasındadır: aşağıdaki uçlar ve alanlar çalışır durumdadır. Mevcut entegrasyonları bozacak bir değişiklik yapmamız gerekirse yöneticilere önceden haber veririz.
- Adres:
https://app.veklam.com - Biçim: JSON, UTF-8. Gövde gönderen isteklerde
Content-Type: application/jsongerekir. - Zaman: ISO 8601, saat dilimiyle (örnek
2026-11-25T14:00:00+03:00). Satış tarihi yalnız gün olarak:2026-11-28. - Para: Türk lirası, sayı olarak (
4250000veya4250000.50).
| Uç | Ne yapar |
|---|---|
POST /api/v1/leads | Yeni talep ekler |
GET /api/v1/leads | Talepleri listeler |
PATCH /api/v1/leads/:ref | Aşama, teklif tutarı, sonraki adım veya kayıp nedenini günceller |
POST /api/v1/leads/:ref/sales | Satış kaydeder, talebi “Satış” aşamasına geçirir |
GET /api/v1/events | Talep geçmişindeki olayları sırayla verir |
API anahtarı
Anahtarı şirketinizin yöneticisi Veklam'da Ayarlar → API ve webhook bölümünden oluşturur. Anahtar yalnızca oluşturulduğu anda bir kez gösterilir; Veklam anahtarın kendisini değil, tek yönlü özetini saklar. Aynı anda en fazla 10 etkin anahtar olabilir; kullanılmayan anahtarı aynı ekrandan kapatın.
Her istekte başlıkta gönderin:
Authorization: Bearer vk_ANAHTARINIZAnahtar şirketinizin bütün taleplerine erişir. Yalnızca sunucu tarafında saklayın; web sayfasına, mobil uygulamaya veya herkese açık bir depoya koymayın. Sızdığını düşünüyorsanız anahtarı hemen kapatıp yenisini oluşturun.
Talep ekleme
POST /api/v1/leads — Talep, panelden veya formdan gelen taleplerle aynı kurallardan geçer: telefon numarası biçimlendirilir, tekrar kontrolü yapılır, sıradaki temsilciye atanır ve geçmişe yazılır.
| Alan | Zorunlu | Açıklama |
|---|---|---|
full_name | Evet | Ad soyad, en fazla 200 karakter |
phone | Evet | Telefon; 0532…, +90532… veya boşluklu yazılabilir |
email | Hayır | E-posta |
source | Hayır | Web formu (varsayılan), Telefon, WhatsApp, Meta, Google, Diğer |
campaign_name | Hayır | Kampanya adı; yoksa oluşturulur |
external_id | Hayır | Sizin sisteminizdeki kayıt numarası; sonraki isteklerde ext: ile kullanılır |
gclid, fbclid, utm_source | Hayır | Reklam tıklama kimlikleri ve kaynak etiketi; satışın kampanyaya bağlanmasını sağlar |
company, message | Hayır | Şirket ve müşteri mesajı |
call_consent | Hayır | Müşteri aranmaya ve WhatsApp ile yazılmaya izin verdi mi; varsayılan false. İzinsiz talepte Ara ve WhatsApp düğmeleri kapalı kalır. |
marketing_consent | Hayır | Ticari ileti onayı; varsayılan false |
curl -X POST https://app.veklam.com/api/v1/leads \
-H "Authorization: Bearer vk_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-d '{
"full_name": "Ayşe Yılmaz",
"phone": "0532 111 22 33",
"source": "Web formu",
"campaign_name": "Kasım – Proje sitesi",
"external_id": "crm-48213",
"call_consent": true
}'Başarılı yanıt 201: { "id": "<Veklam talep kimliği>" }
Tekrar gönderim: Aynı external_id ile gelen istek yeni talep oluşturmaz, mevcut talebin kimliğini döner. Aynı telefonla son 24 saat içinde talep varsa yine mevcut talebin kimliği döner ve talep geçmişine “tekrar başvuru” notu düşülür. Bu sayede ağ hatasında isteği güvenle yeniden gönderebilirsiniz.
Talepleri okuma
GET /api/v1/leads — Talepler eskiden yeniye sıralı gelir.
| Parametre | Açıklama |
|---|---|
created_since | Bu andan sonra (dahil) oluşturulan talepler |
limit | 1–200, varsayılan 200 |
curl "https://app.veklam.com/api/v1/leads?created_since=2026-11-01T00:00:00%2B03:00&limit=200" \
-H "Authorization: Bearer vk_ANAHTARINIZ"Yanıt { "leads": [ … ] }. Her talepte: id, full_name, phone, email, company, message, source, stage, created_at, external_id, call_consent, marketing_consent, offer_amount_tl, next_action_at, next_action_note.
Sonraki sayfa için son kaydın created_at değerini created_since olarak gönderin. Bu değer dahil olduğu için son kayıt bir kez daha gelebilir; kayıtları id ile tekilleştirin.
Aşama güncelleme
PATCH /api/v1/leads/:ref — :ref Veklam talep kimliği ya da ext: önekiyle sizin kayıt numaranızdır (örnek ext:crm-48213). En az bir alan gönderin.
| Alan | Açıklama |
|---|---|
stage | yeni, ulasilamadi, gorusuldu, randevu, teklif, kaybedildi. “Satış” için aşağıdaki satış ucunu kullanın. |
lost_reason | Kayıp nedeni, en fazla 200 karakter. kaybedildi için zorunlu. |
offer_amount_tl | Teklif tutarı |
next_action_at, next_action_note | Sonraki adımın zamanı ve kısa notu (en fazla 280 karakter); temsilcinin Bugün ekranında görünür |
curl -X PATCH https://app.veklam.com/api/v1/leads/ext:crm-48213 \
-H "Authorization: Bearer vk_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-d '{ "stage": "randevu", "next_action_at": "2026-11-25T14:00:00+03:00", "next_action_note": "Ofis ziyareti" }'Başarılı yanıt 200: { "id": "…" }. Her değişiklik talep geçmişine yazılır ve reklam platformu bildirimlerini tetikler (bkz. ölçüm yöntemi).
Satış kaydetme
POST /api/v1/leads/:ref/sales — Satışı kanıt türüyle kaydeder ve talebi “Satış” aşamasına geçirir. Aşama değişikliği başarısız olursa satış kaydı geri alınır; yarım kayıt kalmaz.
| Alan | Zorunlu | Açıklama |
|---|---|---|
amount_tl | Evet | Satış tutarı, sıfırdan büyük |
sold_at | Evet | Satış günü, YYYY-AA-GG |
evidence_type | Hayır | sozlesme (varsayılan), kapora, fatura, tahsilat |
unit_label | Hayır | Satılan birim: daire, araç, program, paket |
curl -X POST https://app.veklam.com/api/v1/leads/ext:crm-48213/sales \
-H "Authorization: Bearer vk_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-d '{ "amount_tl": 4250000, "sold_at": "2026-11-28", "unit_label": "B blok 12", "evidence_type": "sozlesme" }'Başarılı yanıt 201: { "id": "<satış kimliği>", "lead_id": "…" }. Satış iptali şimdilik yalnızca panelden, nedeni yazılarak yapılır.
Olay akışı
GET /api/v1/events?since=…&limit=… — Talep geçmişindeki olayları eskiden yeniye verir; limit 1–500. Webhook kuramayan sistemler bu ucu düzenli aralıkla sorgulayarak değişiklikleri alabilir.
Her olayda type, payload, lead_id, created_at vardır. Türler: olusturuldu, asama_degisti, ilk_temas, temas, randevu, satis, not.
Webhook
Yönetici Ayarlar → API ve webhook bölümünde bir HTTPS adresi ve dinlenecek olayları seçer; en fazla 5 adres tanımlanabilir. Kayıt sırasında bir kez gösterilen gizli anahtar imza doğrulamada kullanılır.
| Olay | Ne zaman |
|---|---|
lead.created | Yeni talep oluştu |
lead.stage_changed | Aşama değişti; data içinde from ve to da gelir |
sale.created | Satış kaydedildi |
sale.canceled | Satış iptal edildi |
İstek POST ile, JSON gövdeyle gelir:
{
"event": "sale.created",
"created_at": "2026-11-28T08:42:05.311+00:00",
"data": {
"lead_id": "6f1c…",
"outcome_id": "a93e…",
"amount_tl": 4250000,
"sold_at": "2026-11-28",
"unit_label": "B blok 12",
"evidence_type": "sozlesme",
"lead": { "id": "6f1c…", "external_id": "crm-48213", "stage": "satis", "source": "Meta", "campaign": "Kasım – Proje sitesi", … }
}
}| Başlık | Anlamı |
|---|---|
X-Veklam-Event | Olay adı |
X-Veklam-Delivery | Gönderim numarası; aynı gönderim tekrar gelirse bununla tekilleştirin |
X-Veklam-Timestamp | Gönderim anı (Unix saniye) |
X-Veklam-Signature | sha256= + HMAC-SHA256(gizli anahtar, zaman.gövde), onaltılık |
İmzayı doğrulama (Node.js)
import crypto from "node:crypto";
// rawBody: isteğin gövdesi, JSON'a çevrilmeden önceki metin hâli
export function veklamImzaDogru(rawBody, headers, secret) {
const ts = headers["x-veklam-timestamp"];
const gelen = headers["x-veklam-signature"] ?? "";
const beklenen = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
const ayni = gelen.length === beklenen.length && crypto.timingSafeEqual(Buffer.from(gelen), Buffer.from(beklenen));
const taze = Math.abs(Date.now() / 1000 - Number(ts)) < 300; // 5 dakikadan eski isteği reddedin
return ayni && taze;
}Teslim ve tekrar deneme
- 10 saniye içinde
2xxyanıt verin; ağır işi kuyruğa alıp sonra yapın. - Başarısız gönderim toplam 6 kez denenir; aralar 2, 4, 8, 16 ve 32 dakikadır.
- Üst üste 50 başarısız denemede adres kapatılır; yönetici Ayarlar'dan yeniden açabilir.
- Olaylar sırasız gelebilir; sıralama için
created_atdeğerini kullanın.
Web sitesi formu
Kendi sitenizdeki formu bağlamanın en kolay yolu, formu gönderen sunucu kodunuzdan POST /api/v1/leads çağırmaktır. Alternatif olarak Veklam'da Ayarlar → Talep alma adresi bölümündeki adres ve şirket anahtarı (org_token) kullanılabilir. Bu anahtarı da yalnızca sunucu tarafında kullanın; web sayfasının kodunda görünürse başkaları sizin adınıza sahte talep gönderebilir. Hangisini seçerseniz seçin, tıklama kimliklerini (gclid, fbclid) ve UTM kaynağını formla birlikte gönderin; satışın doğru kampanyaya yazılması buna bağlıdır.
Hata kodları
Hata yanıtı { "error": "<kod>" } biçimindedir.
| HTTP | Kod | Ne yapmalı |
|---|---|---|
| 400 | invalid_payload | JSON biçimini, alan adlarını ve türlerini kontrol edin. Tanımsız alan gönderilmemelidir. |
| 401 | unauthorized | Anahtar eksik, hatalı veya kapatılmış |
| 404 | not_found | Talep bu şirkette yok veya ext: numarası eşleşmedi |
| 413 | payload_too_large | Gövde 64 KB'tan büyük |
| 422 | missing_fields | Ad soyad ve telefon gerekli |
| 422 | lost_requires_reason | kaybedildi aşamasıyla birlikte lost_reason gönderin |
| 422 | satis_requires_outcome | “Satış” aşaması için satış ucunu kullanın |
| 422 | invalid_change | Değişiklik kurallara uymuyor; değerleri kontrol edin |
| 429 | rate_limited | Kısa sürede çok fazla talep geldi; bir dakika bekleyip yeniden deneyin |
| 500 | server_error | Bizim tarafımızda bir sorun var; isteği yeniden deneyebilirsiniz |
Sınırlar ve veri
- Şirket başına dakikada en fazla 60 yeni talep alınır (panel dışı kaynakların toplamı).
- İstek gövdesi en fazla 64 KB olabilir. Liste uçları bir seferde en fazla 200 talep veya 500 olay döner.
- API ve webhook yanıtlarında müşterinin adı, telefonu ve e-postası bulunur. Bu verileri yalnızca kendi şirketinizin satış işi için ve gizlilik politikamıza uygun şekilde işleyin; webhook adresiniz HTTPS ve erişimi kısıtlı olmalıdır.
- API anahtarı şirket düzeyindedir. Ekip içindeki “temsilci yalnız kendi talebinin telefonunu görsün” ayarı panel kullanıcıları içindir; API anahtarına uygulanmaz.
Sorunuz veya entegrasyon talebiniz için iletişim sayfasından bize yazın; kurulumda yardımcı oluruz.