Geliştiriciler

Kartlarınız, kendi sistemlerinizde

İK sisteminizi, intranetinizi, CRM'inizi ya da yapay zekâ asistanınızı firmanızın dijital kartvizitlerine kendi API anahtarınızla bağlayın. Her anahtar yalnızca seçtiğiniz yetkilerle çalışır.

API erişimi Enterprise paketinde. Paketleri görün

Başlangıç

Panelde API Anahtarları ekranını açın ve anahtar oluşturun. Yalnızca entegrasyonun ihtiyaç duyduğu yetkileri seçin.
Anahtarı hemen kopyalayın; bir kez gösterilir. Biz yalnızca karmasını saklarız.
Anahtarı Authorization başlığıyla gönderin ve bağlantıyı /api/v1/me ile test edin.

curl https://digicardsystem.com/api/v1/me \
  -H "Authorization: Bearer dcs_…"

Yetkiler

Yetki	Ne sağlar
`cards:read`	Kartları okuma: liste ve ayrıntı, kart ve vCard adresleri.
`cards:write`	Kart açma, bilgileri güncelleme, pasif ya da aktif yapma. Paket kart sınırı geçerlidir.
`leads:read`	Kart sayfalarındaki formdan gelen talepleri okuma.

Uçlar

İstek	Yetki	Açıklama
`GET /api/v1/me`	—	Bağlantı testi: anahtarın firması, yetkileri, paket sınırları ve kullanım.
`GET /api/v1/cards`	cards:read	Kartlar. Sorgu: q (ad, e-posta, adres), status (active \| inactive \| all), page, pageSize (en çok 100).
`GET /api/v1/cards/{id}`	cards:read	Tek kart.
`POST /api/v1/cards`	cards:write	Yeni kart. firstName ve lastName zorunlu; slug verilmezse ad soyaddan, company verilmezse firmanın varsayılan şirket adından. Başarıda 201.
`PATCH /api/v1/cards/{id}`	cards:write	Güncelleme: yalnızca gönderilen alanlar değişir; null ya da gönderilmeyen alan değişmez, "" alanı temizler. Önceki hâl panelde geri yüklenebilir.
`POST /api/v1/cards/{id}/deactivate`	cards:write	Kartı pasif yapar (ör. çalışan ayrıldı). Silme yok.
`POST /api/v1/cards/{id}/activate`	cards:write	Kartı yeniden aktif yapar.
`GET /api/v1/leads`	leads:read	Talepler, en yeniden eskiye. Sorgu: since (ISO 8601; yalnızca sonrası), cardId, page, pageSize.

Listeler şu biçimde döner: { "items": [...], "page": 1, "pageSize": 50, "total": 128 }. Tarihler ISO 8601 (UTC), alan adları camelCase.

Örnek: yeni çalışana kart

İK sisteminiz çalışan işe başladığı gün kartını açabilir, ayrıldığı gün pasif yapabilir:

curl -X POST https://digicardsystem.com/api/v1/cards \
  -H "Authorization: Bearer dcs_…" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Ayşe", "lastName": "Yılmaz", "title": "Satış Müdürü",
        "department": "Satış", "email": "ayse@firma.com.tr", "mobile": "0532 000 00 00" }'

Doğrulama hatasında 400 ve alan bazında neden döner; paketin kart sınırı doluysa 403. Fotoğraf, logo, NFC ve şablon panelden yönetilir.

Örnek yanıt

GET /api/v1/me

{
  "company": { "id": "7d3c…", "slug": "ornek-firma", "name": "Örnek Firma" },
  "plan": { "code": "Enterprise", "name": "Enterprise", "maxCards": 12, "maxUsers": 3 },
  "usage": { "activeCards": 9, "activeUsers": 3 },
  "key": { "prefix": "dcs_Ab12Cd34", "scopes": ["cards:read", "cards:write", "leads:read"], "expiresAt": null }
}

Hatalar ve sınırlar

Hatalar application/problem+json biçiminde, kısa bir açıklamayla döner; açıklama Accept-Language başlığına göre Türkçe ya da İngilizcedir.

Kod	Anlamı
`400`	Geçersiz istek parametresi.
`401`	Anahtar yok, geçersiz kılınmış ya da süresi dolmuş.
`403`	Anahtarın yetkisi yok, paket API erişimi içermiyor, abonelik aktif değil ya da kart sınırı dolu.
`404`	Bulunamadı (ya da başka bir firmaya ait).
`429`	Anahtar başına dakikada 120 istek aşıldı; Retry-After kadar bekleyin.

Güvenlik

Bir anahtar yalnızca kendi firmasının verisini görür; API'de çerez ve panel oturumu dikkate alınmaz.
Anahtarı sunucudan sunucuya kullanın; web sayfasına ya da mobil uygulamaya gömmeyin.
Her entegrasyon için ayrı anahtar oluşturun, şüphede panelden geçersiz kılın; diğerleri çalışmaya devam eder.
Her anahtarın son kullanımı panelde görünür.
Her zaman https:// kullanın. http:// adresine gönderilen anahtar yönlendirmeden önce şifresiz gider; böyle olduysa anahtarı geçersiz kılın.
Anahtar sınırına ek olarak IP adresi başına dakikada en çok 600 istek; istek gövdesi en çok 64 KB (üstü 413).
Talepleri okuyan yapay zekâ asistanına yalnızca okuma yetkisi verin: talep metinlerini anonim ziyaretçiler yazar ve asistana yönelik talimat içerebilir.

Ayrıca: Güvenlik sayfası · Yöneticiler için kullanım kılavuzu

Sürüm politikası

/api/v1 içinde yalnızca geriye dönük uyumlu değişiklik yapılır: yeni uç ve yeni alan eklenebilir; tanımadığınız alanları yok sayın.
Uyumsuz bir değişiklik yeni sürüm yoluyla (/api/v2) gelir ve önceden duyurulur; geçiş süresince v1 çalışmaya devam eder.

Yapay zekâ asistanınızı bağlayın (MCP)

Kendi yapay zekâ asistanınız Model Context Protocol ile aynı anahtar ve yetkilerle kartlarınızla çalışabilir: "yeni satış müdürümüze kart aç", "ayrılan çalışanın kartını pasif yap", "bu haftaki talepleri listele". Asistanın yapay zekâ kullanımı sizin kendi aboneliğinizdedir.

Adres (Streamable HTTP): https://digicardsystem.com/mcp

Araç	Yetki	Ne yapar
`get_company`	—	Firma, paket, sınırlar ve anahtarın yetkileri
`list_cards`	cards:read	Kartları listeler ve arar
`get_card`	cards:read	Tek kart
`create_card`	cards:write	Yeni kart açar (paket kart sınırı geçerli)
`update_card`	cards:write	Kartı günceller; önceki hâl panelde geri yüklenebilir
`deactivate_card`	cards:write	Kartı pasif yapar
`activate_card`	cards:write	Kartı yeniden aktif yapar
`list_leads`	leads:read	Kart formundan gelen talepler

Claude Code ile:

claude mcp add --transport http digicardsystem https://digicardsystem.com/mcp \
  --header "Authorization: Bearer dcs_…"

JSON ile ayarlanan istemciler (ör. Cursor):

{
  "mcpServers": {
    "digicardsystem": {
      "url": "https://digicardsystem.com/mcp",
      "headers": { "Authorization": "Bearer dcs_…" }
    }
  }
}

Anahtarı istek başlığıyla gönderebilen MCP istemcileriyle çalışır. OAuth ile oturum açtıran tarayıcı bağlayıcıları henüz desteklenmiyor. MCP ile yapılan her değişiklik denetim kaydına "mcp" kanalıyla yazılır.

OpenAPI

Tüm uçların makine okunur tanımı: /openapi.json (OpenAPI 3). Postman'e, kod üreticinize ya da bir yapay zekâ ajanına aktarabilirsiniz.

API anahtarı oluştur Paketler