Geliştirici API'si

Kendi sisteminden etkinlik oluştur

Her etkinlik türü için tek bir POST. İçeriğini JSON olarak gönder; karşılığında Puzzel.org hesabında bir etkinlik ve oyunculara verebileceğin ya da bir iframe'e yerleştirebileceğin bir URL al.

Temel URL: https://puzzel.org/api/public/v1
Kimlik doğrulama: Gövdede anahtar + e-posta
Uç noktalar: 38 etkinlik türü
Kota: Günde 10 etkinlik

İlk isteğin

Kurulacak bir şey yok, el sıkışma da yok: anahtarını, e-posta adresini ve içeriğini taşıyan bir JSON gövdesi gönder. Gelen cevapta yeni etkinliğin anahtarı ve oynandığı URL yer alır.

POST crossword

curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "tr",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'

Başarılı

{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Bu sayfadaki her örnek eksiksiz ve çalıştırılabilir bir istektir. Kendi anahtarını ve içeriğini koy, olduğu gibi çalışır.

Kimlik doğrulama

Ne header var ne de bearer token. İki kimlik bilgisi de her isteğin JSON gövdesinde gider ve anahtar yalnızca o e-postanın ait olduğu hesap için geçerlidir.

Alan	Tür	Ne işe yarar
`account_api_key` zorunlu string	string	Hesabının API anahtarı. Header'a değil, gövdeye konur.
`email` zorunlu string	string	Puzzel.org hesabının giriş yaptığı adres. Anahtar yalnızca onunla birlikte geçerlidir.

Anahtarın, panelindeki hesap bölümünde, Göster düğmesinin arkasında duruyor.

Giriş yap

API anahtarları abonelik başladığında verilir; yani ücretsiz bir hesapta henüz yoktur.

Paketleri gör

Anahtara bir şifre gibi davran. Hesabında etkinlik oluşturur ve var olanların üzerine yazar; bu yüzden onu sunucu tarafında tut, tarayıcının okuyabileceği hiçbir yere koyma.

İstek gövdesi

Her uç nokta aynı beş alanı alır. Farklı olan, altlarındaki içerik alanı: çoğu bir items dizisi alır, birkaçı tek bir cümle ya da tek bir görsel alır, sudoku ise hiçbir şey almaz.

Alan	Tür	Ne işe yarar
`account_api_key` zorunlu string	string	Hesabının API anahtarı. Header'a değil, gövdeye konur.
`email` zorunlu string	string	Puzzel.org hesabının giriş yaptığı adres. Anahtar yalnızca onunla birlikte geçerlidir.
`title` isteğe bağlı string	string	Etkinliğin panelinde alacağı ad. Boş bırak, uç nokta kendi yedek adını kullanır.
`language` isteğe bağlı string	string	Yalnızca dönen URL'deki dili belirler — gönderdiğin hiçbir şeyi çevirmez. Kelime avı ayrıca bunu okur ve "ar" olduğunda dolgu harflerini Arapçaya geçirir. Varsayılan: "en"
`activity_key` isteğe bağlı string	string	Yeni bir etkinlik oluşturmak için boş bırak. Zaten sahibi olduğun bir etkinliğin anahtarını gönderirsen, onun yerine o etkinlik yeniden oluşturulur.

settings, uç noktaya özel seçeneklerden oluşan bir nesnedir. Bir uç noktanın hangilerini okuduğu aşağıda onunla birlikte listelenir; oraya koyduğun başka her şey yok sayılır.

Ne geri döner

Başarılı bir çağrı, yeni etkinliğin anahtarı ve oynandığı URL ile 200 cevabı verir. Diğer her durumda success false olur ve tek bir error metni döner.

Başarılı

{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Başarısız

{
  "success": false,
  "error": "Invalid Email or API Key"
}

Dönen url, yerleştirme görünümüdür. Tam sayfa açmak için embed yerine play, düzenleyicide açmak için build yaz — p= sonrasındaki anahtar aynı kalır.

Oluşturma ve güncelleme

activity_key gönder, arkasındaki etkinlik yerinde yeniden oluşturulsun: içeriği değişir, adı ve sürüm damgası tazelenir, anahtarın kendisi ise aynı kalır — böylece daha önce paylaştığın bağlantılar ve yerleştirmeler çalışmaya devam eder. Sonuçlar, klasör yerleşimi ve uç noktanın kendisinin yazmadığı her ayar olduğu gibi kalır.

activity_key

{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "activity_key": "-Nq8sample_activity_key",
  "title": "Fruit crossword, week 2",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}

title her güncellemede uygulanır, varsayılanı da dahil — boş bırakırsan etkinlik o uç noktanın yedek adıyla yeniden adlandırılır.
Bir uç noktanın kendi yazdığı ayar blokları sıfırdan yeniden yazılır; yani bir güncelleme bunları da gönderdiğin değerlere ya da uç noktanın varsayılanlarına döndürür.
Yalnızca kendi hesabının sahibi olduğu etkinlikleri güncelleyebilirsin. Başkasına ait bir anahtar 403 cevabı alır.
Bir güncelleme, oluşturmayla aynıya mal olur: bugünkü kotadan bir çağrı.

İstek sınırı

Hesap başına günde 10 etkinlik

Başarılı her çağrı sayılır; oluşturma da güncelleme de. Sınırı aşarsan sayaç sıfırlanana kadar sonraki istek 429 cevabı alır.

Sayaç, kayan 24 saatlik bir pencereye göre değil, zamanlanmış bir işle günde bir kez sıfırlanır.

Hatalar

Hatalar her zaman aynı iki alanla JSON olarak gelir, asla HTML sayfası olarak değil. error metni bir insanın okuması için yazılır — sorun çıkaran alanı ya da sınırı adıyla söyler.

Durum	Ne anlama gelir
`400` Bad Request	Gövdedeki bir şey eksik, bozuk ya da aralık dışında. Mesaj, hangi alan olduğunu söyler.
`401` Unauthorized	E-posta bilinmiyor ya da anahtar o hesaba ait değil.
`403` Forbidden	Gönderdiğin activity_key başka bir hesaba ait.
`429` Too Many Requests	Bugünkü kota doldu. Günde bir kez sıfırlanır.
`500` Server Error	Oluşturucu, gönderdiklerinden bir bulmaca kuramadı — genellikle kelime sayısı çok az ya da kelimeler birbirine oturmuyor.

Uç noktalar

Her etkinlik türü için bir yol; hepsi POST, hepsi aynı temel URL altında. Her biri ihtiyaç duyduğu içeriği, okuduğu ayarları ve çalıştırabileceğin bir isteği listeler.

Kelimeler ve harfler

Çengel bulmaca

Cevaplarını bir ızgarada birbirine geçirir ve tanımları senin için numaralandırır.

POST /api/public/v1/crossword items içinde 2 ile 80 arasında öğe

İçerik

Bir kelime dizisi. Her kayıt, cevabı onu işaret eden tanımla eşleştirir.

Yedek ad olarak “Crossword API” kullanılır

Bilmekte fayda var

İki karakterden kısa cevaplar ızgara kurulmadan önce elenir ve bundan en az iki tanesinin sağ çıkması gerekir.
Cevaplar büyük harfe çevrilir ve oluşturucunun bunları yerleştirmek için yirmi denemesi olur. Tek bir kelimeyi bile yerleştiremezse çağrı 500 cevabı verir.

Okuduğu ayarlar

Alan	Tür	Ne işe yarar
`hidden_solution` isteğe bağlı settings içinde string	string	İsteğe bağlı bir bonus kelime. Harfleri bitmiş ızgaranın hücrelerinde işaretlenir; oyuncular çengel bulmacayı çözdükten sonra bunları toplar. Bu yüzden harflerinin her biri cevapların içinde geçmek zorundadır.

Örnek istek

POST crossword

curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "tr",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'

Başarılı

{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Alan	Tür	Ne işe yarar
`hidden_solution` isteğe bağlı settings içinde string	string	Artan harfler bunu yazar. Bunu ayarlamak ayrıca oluşturucuya, olabildiğince çok kelime sıkıştırmak yerine önce çözümü yerleştirmesini söyler.
`directions` isteğe bağlı settings içinde string[]	string[]	Bir kelimenin hangi yönlerde uzanabileceği. Boş bırak, kelimeler yalnızca doğuya, güneydoğuya ve güneye uzanır. Şunlardan biri `westeastnorthsouthnorthwestnortheastsouthwestsoutheast` Varsayılan: ["east", "southeast", "south"]
`template` isteğe bağlı settings içinde string	string	Izgarayı kare bırakmak yerine bir şekle göre keser. Şunlardan biri `squarecirclecrossdiamondpyramidsmileystarcross_plus`

Alan	Tür	Ne işe yarar
`theme` isteğe bağlı settings içinde string	string	Izgaranın üstünde gösterilen bilmece. Boş bırakılırsa oyuncular başlığı görür.
`spangram` isteğe bağlı settings içinde string	string	Temayı adlandıran ve tahtayı bir kenardan diğerine kesen kelime ya da ifade.

Alan	Tür	Ne işe yarar
`list_match_mode` isteğe bağlı settings içinde string	string	Bir adın yazıldığı anda mı, yoksa yalnızca Enter tuşuna basınca mı sayılacağı. Şunlardan biri `while_typingon_enter` Varsayılan: "while_typing"
`list_slot_hint` isteğe bağlı settings içinde string	string	Boş bir yuvanın neyi ele verdiği: hiçbir şeyi, adın uzunluğunu, ilk harfini ya da yazdığın ipucunu. Şunlardan biri `nonelengthfirst_letterhint` Varsayılan: "none"
`list_arrange` isteğe bağlı settings içinde string	string	Her grup için bir sütun ya da tek bir liste. Şunlardan biri `groupsone_list` Varsayılan: "groups"
`list_allow_give_up` isteğe bağlı settings içinde boolean	boolean	Turu bitiren ve kaçırılanları gösteren bir pes et düğmesi gösterir. Varsayılan: false

Alan	Tür	Ne işe yarar
`mode` isteğe bağlı settings içinde string	string	Hücreleri neyin doldurduğu: öğelerin, ipucuyla çağrılan öğelerin ya da düz sayılar (öğe gerekmez). Şunlardan biri `itemscluesnumbers` Varsayılan: "items"
`rows` isteğe bağlı settings içinde number	number	Her kartta satır sayısı, 2 ile 5 arasında. Varsayılan: 3
`columns` isteğe bağlı settings içinde number	number	Her kartta sütun sayısı, 2 ile 5 arasında. Varsayılan: 3
`highest_number` isteğe bağlı settings içinde number	number	numbers modunda kartlar 1'den bu sayıya kadar doldurulur, en fazla 100. Bir paket özelliği: paketin yoksa 50 olarak kalır. Varsayılan: 50

Alan	Tür	Ne işe yarar
`instructions` isteğe bağlı settings içinde string	string	Kodun cevapladığı soru ya da bilmece; kartlarla birlikte gösterilir.
`force_solution_in_correct_order` isteğe bağlı settings içinde boolean	boolean	Kartlara sırayla basılmalıdır. Kapalıyken doğru kartların herhangi bir sırası kilidi açar. Varsayılan: false
`randomize_order` isteğe bağlı settings içinde boolean	boolean	Her oyuncu kartları karışık bir düzende alır. Varsayılan: true

Alan	Tür	Ne işe yarar
`number_of_tiles` isteğe bağlı settings içinde number	number	Oyun tahtasında kaç kare olduğu. 10 ile 75 arasında. Varsayılan: 30
`game_mode` isteğe bağlı settings içinde string	string	Oyuncuların bitişe mi yarıştığı, yoksa yol boyunca nesne mi topladığı. Şunlardan biri `race_to_finishcollect_items` Varsayılan: "race_to_finish"

Alan	Tür	Ne işe yarar
`maze_width` isteğe bağlı settings içinde string	string	Odaların nasıl dizildiği: tek sütun, kare ya da daha geniş. Şunlardan biri `narrownormalwide` Varsayılan: "normal"
`maze_corridors` isteğe bağlı settings içinde string	string	İki soru arasında ne kadar labirent olduğu. Şunlardan biri `shortnormallong` Varsayılan: "normal"
`maze_fog` isteğe bağlı settings içinde string	string	Labirentin tamamını göster ya da yalnızca oyuncunun yanından geçtiği yerleri. Şunlardan biri `offnear` Varsayılan: "off"
`maze_wrong_door_pause` isteğe bağlı settings içinde string	string	Yanlış bir kapıdan sonra kapıların ne kadar süre kapalı kalacağı. Şunlardan biri `noneshortlong` Varsayılan: "short"
`maze_walk_there` isteğe bağlı settings içinde boolean	boolean	Jetonu bir sonraki odaya yürüten bir düğme sunar. Varsayılan: false
`maze_seed` isteğe bağlı settings içinde string	string	Labirentin üretildiği tohum. Aynı tohum ve aynı sorular aynı labirenti verir; boş bırakılırsa yeni bir tane çekilir.

Alan	Tür	Ne işe yarar
`jeopardy_buzzer_mode` isteğe bağlı settings içinde string	string	Kim nasıl oynar: oyun yöneticisi konsoldan yönetir, oyuncular telefonlarından zile basar ya da her oyuncu tahtayı tek başına oynar. Şunlardan biri `hostphonessolo` Varsayılan: "host"
`jeopardy_contestants` isteğe bağlı settings içinde string	string	Konsolun takımlardan mı yoksa oyunculardan mı söz edeceği. Şunlardan biri `teamsplayers` Varsayılan: "teams"
`jeopardy_value_step` isteğe bağlı settings içinde number	number	Bir satırın değeri: bir ipucunun değeri, bu sayının satır numarasıyla çarpımıdır. 50 ile 500 arasında, 50'şer adımla. Varsayılan: 100
`jeopardy_answer_time` isteğe bağlı settings içinde number	number	Bir ipucu açıldıktan sonra cevap için verilen saniye, en fazla 300. 0 süresiz demektir. Varsayılan: 20
`jeopardy_wrong_answer_costs` isteğe bağlı settings içinde boolean	boolean	Yanlış bir cevap, ipucunun değerini puandan düşer. Varsayılan: false
`jeopardy_reveal_on_timeout` isteğe bağlı settings içinde boolean	boolean	Süre dolduğunda tahta cevabı kendisi gösterir. Varsayılan: false
`jeopardy_require_question_form` isteğe bağlı settings içinde boolean	boolean	Oyunculara cevabı soru biçiminde vermelerini hatırlatır. Varsayılan: false

Alan	Tür	Ne işe yarar
`video_url` zorunlu settings içinde string	string	Video: bir YouTube, Vimeo ya da Bunny Stream sayfası veya bir mp4, webm ya da mov dosyasına doğrudan bağlantı.
`video_duration` isteğe bağlı settings içinde number	number	Videonun saniye cinsinden uzunluğu. Verildiğinde, bitişin ötesine konan bir açılır pencere reddedilir.

Alan	Tür	Ne işe yarar
`sentence` zorunlu string	string	Şifrelenecek cümle. Oyuncular onu karakter karakter çözer.
`helpers` isteğe bağlı settings içinde string	string	Başlangıç kolaylığı olarak hangi karakterlerin baştan verileceği: hiçbiri, en sık geçenler, ünlüler ya da kendi listelediklerin. Şunlardan biri `nonemost_commonvowelscustom` Varsayılan: "none"
`character_list` isteğe bağlı settings içinde string	string	Şifrenin kurulduğu alfabe. Boş bırakılırsa şifreleme kendi alfabesini seçer.
`extra_letters` isteğe bağlı settings içinde string	string	helpers "custom" olduğunda baştan verilen karakterler. Diğer yardım modlarında yok sayılır.
`hide_unused_characters` isteğe bağlı settings içinde boolean	boolean	Cümlede hiç kullanılmayan karakterleri anahtarın dışında bırakır. Varsayılan: false

Alan	Tür	Ne işe yarar
`sentence` zorunlu string	string	Oyuncuların işlemleri çözerek ortaya çıkardığı cümle.
`difficulty_level` isteğe bağlı settings içinde number	number	Bir işlemin verebileceği en yüksek cevap. Şunlardan biri `20501001000` Varsayılan: "100"
`operators` isteğe bağlı settings içinde string[]	string[]	Hangi işlem türlerinin görünebileceği. x çarpma, : bölmedir. Şunlardan biri `+-x:` Varsayılan: ["+", "-", "x", ":"]
`max_operations` isteğe bağlı settings içinde number	number	Bir işlemde en fazla kaç adımın arka arkaya zincirlenebileceği. Şunlardan biri `123` Varsayılan: 1
`number_difficulty` isteğe bağlı settings içinde number	number	Bir işlemin içindeki tek tek sayıları sınırlar. 5 ile 1000 arasında herhangi bir değer. Varsayılan: 100

Alan	Tür	Ne işe yarar
`size` isteğe bağlı settings içinde string	string	Bir bloğun boyutu, satır çarpı sütun olarak yazılır — 3x3 klasik 9x9 ızgarayı verir. Uç nokta yalnızca iki sayı olarak ayrıştırılıp ayrıştırılmadığına bakar; bu yüzden düzenleyicinin sunduğu boyutlarda kal. Şunlardan biri `2x22x33x33x44x4` Varsayılan: "3x3"
`difficulty_level` isteğe bağlı settings içinde string	string	Başlangıç için tahtada kaç sayının bırakılacağı. Şunlardan biri `easynormalhard` Varsayılan: "normal"

Alan	Tür	Ne işe yarar
`sentence` zorunlu string	string	Gizlenecek ifade: bir alıntı, bir atasözü, bir anahtar cümle. En fazla 120 harf ve rakam.
`columns` isteğe bağlı settings içinde number	number	Tahtanın genişliği, 8 ile 18 arasında. Daha dar olursa her sütunda daha çok harf yığılır ve bulmaca zorlaşır. Varsayılan: 14
`helpers` isteğe bağlı settings içinde string	string	Bir başlangıç kolaylığı olarak ızgarada hangi harflerin kalacağı: hiçbiri, en sık geçenler, ünlüler ya da kendi listelediklerin. Şunlardan biri `nonemost_commonvowelscustom` Varsayılan: "none"
`extra_letters` isteğe bağlı settings içinde string	string	helpers "custom" olduğunda baştan verilen harfler.

Alan	Tür	Ne işe yarar
`tables` isteğe bağlı settings içinde number[]	number[]	Çalışılacak tablolar. Boş bırakılırsa 1'den 10'a kadardır; 11 ya da 12 eklersen ızgara 12'ye 12 olur. Şunlardan biri `123456789101112`
`order` isteğe bağlı settings içinde string	string	Satır ve sütunların sırayla mı yoksa karışık mı dizileceği. Şunlardan biri `ascendingshuffled` Varsayılan: "ascending"
`picture` isteğe bağlı settings içinde string	string	Doğru cevapların boyadığı görsel. Şunlardan biri `sailboatheartrockettreecatfishflowerhouse` Varsayılan: "sailboat"
`players_choose_tables` isteğe bağlı settings içinde boolean	boolean	Her oyuncunun hangi tabloları çalışacağını seçmesine izin verir. Varsayılan: false
`fill_same_sums` isteğe bağlı settings içinde boolean	boolean	Tek bir doğru cevap, aynı işlemi veren tüm kareleri doldurur. Varsayılan: true

Alan	Tür	Ne işe yarar
`story` isteğe bağlı settings içinde string	string	İpuçlarının üstünde gösterilen arka plan hikâyesi.
`difficulty` isteğe bağlı settings içinde string	string	Oluşturucunun hangi tür ipuçlarını kullanabileceği. Şunlardan biri `easymediumhard` Varsayılan: "easy"
`hints` isteğe bağlı settings içinde boolean	boolean	Bir sonraki adımı gösteren bir ipucu düğmesi sunar. Varsayılan: true
`auto_cross` isteğe bağlı settings içinde boolean	boolean	Bir eşleşmeyi işaretlemek, onun satırının ve sütununun geri kalanını çizer. Varsayılan: true
`clue_mode` isteğe bağlı settings içinde string	string	Oyuncuların gördüğü ipuçlarını kimin yazdığı: tablodan üretilenler, free_clues içindeki kendi cümlelerin ya da hiçbiri. Şunlardan biri `generatedfreenone` Varsayılan: "generated"
`free_clues` isteğe bağlı settings içinde string[]	string[]	Kendi ipucu cümlelerin; clue_mode "free" iken yazdığın gibi gösterilir. Hiçbiri denetlenmez.

Alan	Tür	Ne işe yarar
`clue_mode` isteğe bağlı settings içinde string	string	Kuralların görsel olarak mı yoksa cümle olarak mı gösterileceği. Şunlardan biri `visualtext` Varsayılan: "visual"
`unique_object_picks` isteğe bağlı settings içinde boolean	boolean	Her şekil yalnızca bir kez yerleştirilebilir. Varsayılan: false
`hide_color_picker` isteğe bağlı settings içinde boolean	boolean	Oyuncular şekillerin rengini değiştiremez. Varsayılan: false

Kendi sisteminden etkinlik oluştur

İlk isteğin

Kimlik doğrulama

İstek gövdesi

Ne geri döner

Oluşturma ve güncelleme

İstek sınırı

Hatalar

Uç noktalar

Bir şey beklendiği gibi çalışmıyor mu?