Organizatör API'si

Ne işe yarar

Organizatör API'si, kendi sistemlerinizin efuar'daki fuarlarınızı ve bu fuarlara katılan firmaları okumasını sağlar. Örneğin muhasebe ya da ERP sisteminiz katılımcı firmaları ve tuttukları stantları kendi kayıtlarına alır, web siteniz fuar takviminizi ya da katılımcı listesini yayımlar, raporlama aracınız fuarlarınızın durumunu izler.

Bu sürüm (v1) yalnız okuma içindir: API ile kayıt oluşturulamaz, değiştirilemez ya da silinemez. Tutarlar (sözleşme, cari hesap, tahsilat) ve kişisel veriler (firmaların kişileri, ziyaretçiler) API'de yoktur. Bir şey olduğunda haberdar olmak için Webhook'lar sayfasına bakın.

Anahtar oluşturmak ve iptal etmek

Anahtarlar Ayarlar › API ve Webhook ekranının API anahtarları sekmesinde yönetilir. Ekranı rolünde API anahtarlarını ve webhook'ları yönetme yetkisi olan kullanıcılar görür; paketinizde API Erişimi özelliği açık olmalıdır.

Yeni anahtar

1. Yeni anahtar kutusuna anahtarı kullanacak sistemi anlatan bir ad yazın (en fazla 100 karakter), örneğin "Muhasebe sistemi".
2. Anahtar oluştur düğmesine tıklayın.
3. Sayfanın üstündeki kutuda görünen anahtarı kopyalayın ve yalnız kullanacak sistemin ayarlarına yazın.
4. API'nin adresini sağdaki Nasıl kullanılır kartından alın.

Anahtar fpk_ ile başlar, ardından büyük harf ve rakamlardan oluşan 40 karakter gelir. Listede yalnız başlangıcı (fpk_ ve ilk sekiz karakter) görünür; anahtarın tamamı bir daha gösterilmez.

Dikkat: Anahtar, onu elinde bulunduran herkese organizatörünüzün bütün şubelerindeki fuarları okuma imkânı verir. Bir parola gibi saklayın: web sayfalarının kodunda, paylaşılan dosyalarda ya da kod depolarında bulunmasın. Sızdığından şüphelenirseniz hemen iptal edin.

Anahtarı iptal etmek ya da değiştirmek

Satırdaki İptal et düğmesi, onay sorusundan sonra anahtarı geçersiz kılar: o andan sonra bu anahtarla yapılan her çağrı reddedilir. İptal geri alınamaz; anahtar listede İptal edildi durumuyla kalır.

Bir anahtarı kesinti olmadan değiştirmek için:

1. Aynı sistem için yeni bir anahtar oluşturun ve sistemin ayarlarına yazın.
2. Yeni anahtarın satırında Son kullanım zamanının göründüğünü denetleyin.
3. Eski anahtarı İptal et ile kapatın.

İsteklerin genel kuralları

• Adres: panelinizin adresi ve /api/v1. Tam adres Nasıl kullanılır kartında yazar; aşağıdaki yollar bu adresin sonuna eklenir.
• Kimlik: anahtar her istekte Authorization başlığıyla gönderilir. Bu başlığı yazamayan bir araç anahtarı X-Api-Key başlığında gönderebilir.

GET /api/v1/fairs HTTP/1.1
Host: panel.ornek.com
Authorization: Bearer fpk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Kapsam: anahtar organizatörünüzündür ve bütün şubelerinizi okur; kullanıcıların şube erişimine bağlı değildir. Başka bir organizatörün kayıtları hiçbir zaman görünmez.
• Biçim: yanıtlar JSON'dur ve alan adları küçük harfle başlar (startDate). Saatler UTC olarak verilir (2026-10-10T08:30:00+00:00), günler yyyy-MM-dd biçimindedir.
• Durumlar İngilizce adlarıyla gelir (OnSale) ve süzgeçte de adlarıyla verilir; büyük ya da küçük harf fark etmez, sayı kabul edilmez.
• Sayfalama: listeler sayfalıdır. page 1'den başlar; pageSize varsayılan olarak 50, en çok 200'dür. Liste yanıtı { "items": [...], "page": 1, "pageSize": 50, "totalCount": 123 } biçimindedir.
• Değişenler: listelerde updatedSince, yalnız o andan sonra oluşturulan ya da değişen kayıtları getirir. Zamanı saat dilimiyle yazın, en kolayı Z ile: 2026-10-01T00:00:00Z. +03:00 gibi bir fark kullanırsanız + işaretini adreste %2B olarak yazın.
• Hız sınırı: aynı internet adresinden dakikada en çok 300 istek kabul edilir; aşılırsa 429 yanıtı gelir.
• API sunucudan sunucuya çağrılmak içindir: başka bir sitede çalışan tarayıcı kodu API'yi çağıramaz. Çağrıları kendi sunucunuzdan yapın.

Uçlar

from ve to gün olarak verilir (2027-01-01); tarihleri bu aralıkla kesişen fuarlar gelir.

Fuar

{
  "id": 229,
  "name": "Örnek Mobilya Fuarı 2027",
  "shortName": "Mobilya 2027",
  "status": "OnSale",
  "startDate": "2027-03-24",
  "endDate": "2027-03-27",
  "venue": "Örnek Fuar Merkezi",
  "city": "Ankara",
  "country": "Türkiye",
  "currency": "EUR",
  "website": "https://mobilya.example",
  "createdAt": "2026-05-02T09:14:00+00:00",
  "updatedAt": null
}

venue fuar alanının adı, currency fuarın para birimidir. Hiç değişmemiş kayıtta updatedAt boştur.

Katılım

{
  "id": 5120,
  "fairId": 229,
  "status": "Confirmed",
  "company": {
    "id": 881,
    "name": "Örnek Ahşap A.Ş.",
    "legalName": "Örnek Ahşap Sanayi ve Ticaret A.Ş.",
    "taxNumber": "1234567890",
    "taxOffice": "Çankaya",
    "city": "Ankara",
    "country": "Türkiye",
    "phone": "+90 312 000 00 00",
    "email": "info@ornekahsap.example",
    "website": "https://ornekahsap.example"
  },
  "roles": ["Exhibitor"],
  "stands": [
    { "id": 77, "code": "A-12", "hall": "A", "width": 4, "depth": 3, "area": 12, "allocation": "Sold", "contracted": true }
  ],
  "createdAt": "2026-06-11T12:00:00+00:00",
  "updatedAt": "2026-07-01T08:30:00+00:00"
}

• company: firmayı tanımaya yeten bilgiler; firmanın kişileri yer almaz.
• stands: firmanın şu an tuttuğu stantlar, stant koduna göre sıralı; bırakılan stantlar yer almaz. hall salonun kodudur, area en ile derinliğin çarpımıdır (ölçü girilmemişse boş).
• allocation standın rezerve mi satılmış mı olduğunu söyler; contracted stant onaylı bir satış sözleşmesiyle satıldıysa true olur.

Değerlerin paneldeki karşılığı

Hata yanıtları

400, 401, 403 ve 404 yanıtlarında gövde standart "problem ayrıntısı" biçimindedir (Content-Type: application/problem+json): status alanı kodu, title alanı İngilizce kısa açıklamayı verir. Başarılı yanıtlar application/json döner.

{ "status": 404, "title": "Fair not found." }

Nasıl yapılır

Anahtarı denemek

1. Anahtarı oluşturun ve kopyalayın.
2. GET /api/v1/me isteğini anahtarla gönderin.
3. Yanıtta organizatörünüzün adını ve anahtara verdiğiniz adı görürsünüz. Ekranda anahtarın Son kullanım sütunu dolar.

Fuar ve katılımcı kopyasını güncel tutmak

1. İlk seferde GET /fairs listesinin bütün sayfalarını okuyun: okunan kayıt sayısı totalCount değerine ulaşana kadar page değerini artırın.
2. Okumaya başladığınız anı (UTC) saklayın.
3. Her fuar için GET /fairs/{id}/participations listesini aynı yolla okuyun.
4. Sonraki seferlerde aynı istekleri updatedSince ile, sakladığınız anı vererek gönderin; yalnız yeni ve değişen kayıtlar gelir. Ardından yeni başlangıç anını saklayın.

GET /api/v1/fairs?status=OnSale&updatedSince=2026-10-01T00:00:00Z&page=1&pageSize=100 HTTP/1.1
Host: panel.ornek.com
Authorization: Bearer fpk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Not: updatedSince, kaydın yanıtta gördüğünüz her parçasının değişimine bakar: bir katılım, firmasının bilgileri, rolleri ya da stantları değiştiğinde de listeye girer; bir fuar, fuar alanının adı değiştiğinde de. Silinen bir fuar ya da katılım ise listelerden çıkar ve bu süzgeç silindiğini bildirmez; kopyanızı zaman zaman listelerin tamamını okuyarak denetleyin.

Kurallar ve dikkat edilecekler

• Bir organizatörde en fazla 10 etkin anahtar olabilir; kartın altında etkin anahtar sayısı yazar. Sınıra ulaşınca kullanılmayan bir anahtarı iptal edin.
• Her sistem için ayrı anahtar oluşturun: biri sızarsa yalnız onu iptal edersiniz, diğer sistemler çalışmayı sürdürür.
• İptal edilen anahtarın kaydı silinmez; kimin ne zaman oluşturduğu listede kalır.
• Son kullanım her çağrıda değil, en çok beş dakikada bir güncellenir.
• Paketinizde API Erişimi kapanırsa ya da aboneliğiniz geçerliliğini yitirirse anahtarlar 403 alır. API Erişimi kapalıyken yeni anahtar da oluşturulamaz.
• API'de olmayanlar: tutarlar, firmaların kişileri, ziyaretçiler ve bırakılmış stantlar. Sözleşme ve tahsilat tutarlarını webhook iletileriyle alabilirsiniz.

İlgili sayfalar

• API ve Webhook
• Webhook'lar
• Fuarlar
• Katılımcılar
• Abonelik