API για προγραμματιστές

Δημιούργησε δραστηριότητες από το δικό σου σύστημα

Ένα POST ανά τύπο δραστηριότητας. Στέλνεις το περιεχόμενό σου σε JSON και παίρνεις πίσω μια δραστηριότητα στον λογαριασμό σου στο Puzzel.org και ένα URL που μπορείς να δώσεις στους παίκτες ή να βάλεις σε ένα iframe.

Βασικό URL: https://puzzel.org/api/public/v1
Ταυτοποίηση: Κλειδί + email στο σώμα
Endpoints: 20 τύποι δραστηριοτήτων
Όριο: 10 δραστηριότητες την ημέρα

Το πρώτο σου αίτημα

Δεν χρειάζεται εγκατάσταση ούτε handshake: στέλνεις ένα σώμα JSON με το κλειδί σου, το email σου και το περιεχόμενό σου. Η απάντηση περιέχει το κλειδί της νέας δραστηριότητας και το URL στο οποίο παίζεται.

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": "gr",
  "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"
    }
  ]
}'

Επιτυχία

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

Κάθε παράδειγμα σε αυτή τη σελίδα είναι ένα πλήρες αίτημα που τρέχει όπως είναι. Βάλε το δικό σου κλειδί και το δικό σου περιεχόμενο και δουλεύει αμέσως.

Έλεγχος ταυτότητας

Δεν υπάρχουν headers ούτε bearer token. Και τα δύο διαπιστευτήρια ταξιδεύουν μέσα στο σώμα JSON κάθε αιτήματος, και το κλειδί γίνεται δεκτό μόνο για τον λογαριασμό στον οποίο ανήκει αυτό το email.

Πεδίο	Τύπος	Τι κάνει
`account_api_key` υποχρεωτικό string	string	Το κλειδί API του λογαριασμού σου. Πηγαίνει στο σώμα, όχι σε header.
`email` υποχρεωτικό string	string	Η διεύθυνση με την οποία συνδέεται ο λογαριασμός σου στο Puzzel.org. Το κλειδί ισχύει μόνο μαζί με αυτήν.

Το κλειδί σου βρίσκεται στην ενότητα λογαριασμού του πίνακα ελέγχου, πίσω από το κουμπί Εμφάνιση.

Σύνδεση

Τα κλειδιά API δίνονται όταν ξεκινά μια συνδρομή, οπότε ένας δωρεάν λογαριασμός δεν έχει ακόμη.

Δες τα προγράμματα

Φύλαξε το κλειδί σαν κωδικό πρόσβασης. Δημιουργεί και αντικαθιστά δραστηριότητες στον λογαριασμό σου, γι' αυτό κράτησέ το στον server και μακριά από οτιδήποτε μπορεί να διαβάσει ένας περιηγητής.

Το σώμα του αιτήματος

Κάθε endpoint δέχεται τα ίδια πέντε πεδία. Αυτό που αλλάζει είναι το πεδίο περιεχομένου από κάτω: τα περισσότερα δέχονται έναν πίνακα items, μερικά μία πρόταση ή μία εικόνα, και το Sudoku δεν δέχεται απολύτως τίποτα.

Πεδίο	Τύπος	Τι κάνει
`account_api_key` υποχρεωτικό string	string	Το κλειδί API του λογαριασμού σου. Πηγαίνει στο σώμα, όχι σε header.
`email` υποχρεωτικό string	string	Η διεύθυνση με την οποία συνδέεται ο λογαριασμός σου στο Puzzel.org. Το κλειδί ισχύει μόνο μαζί με αυτήν.
`title` προαιρετικό string	string	Το όνομα που παίρνει η δραστηριότητα στον πίνακα ελέγχου σου. Άφησέ το κενό και το endpoint χρησιμοποιεί το δικό του εφεδρικό όνομα.
`language` προαιρετικό string	string	Καθορίζει μόνο τη γλώσσα στο URL που παίρνεις πίσω — δεν μεταφράζει τίποτα από όσα στέλνεις. Το κρυπτόλεξο το διαβάζει επίσης για να αλλάξει τα γράμματα γεμίσματος σε αραβικά όταν είναι "ar". Προεπιλογή: "en"
`activity_key` προαιρετικό string	string	Άφησέ το κενό για να δημιουργηθεί νέα δραστηριότητα. Δώσε το κλειδί μιας που ήδη σου ανήκει και τότε ξαναδημιουργείται εκείνη.

Το settings είναι ένα αντικείμενο με επιλογές ανά endpoint. Ποιες διαβάζει το κάθε endpoint αναφέρεται μαζί του παρακάτω· οτιδήποτε άλλο βάλεις εκεί αγνοείται.

Τι παίρνεις πίσω

Μια επιτυχημένη κλήση απαντά 200 με το κλειδί της νέας δραστηριότητας και το URL στο οποίο παίζεται. Οτιδήποτε άλλο απαντά με το success σε false και ένα μόνο string σφάλματος.

Επιτυχία

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

Αποτυχία

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

Το url που παίρνεις πίσω είναι η προβολή ενσωμάτωσης. Άλλαξε το embed σε play για να ανοίξει σε ολόκληρη τη σελίδα ή σε build για να ανοίξει στον επεξεργαστή — το κλειδί μετά το p= μένει το ίδιο.

Δημιουργία ή ενημέρωση

Στέλνεις activity_key και η δραστηριότητα πίσω από αυτό ξαναδημιουργείται επιτόπου: το περιεχόμενό της αντικαθίσταται, το όνομα και η σήμανση έκδοσης ανανεώνονται και το ίδιο το κλειδί μένει το ίδιο — έτσι οι σύνδεσμοι και οι ενσωματώσεις που έχεις ήδη κοινοποιήσει συνεχίζουν να δουλεύουν. Τα αποτελέσματα, ο φάκελος στον οποίο βρίσκεται και κάθε ρύθμιση που δεν γράφει το ίδιο το endpoint μένουν όπως ήταν.

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 εφαρμόζεται σε κάθε ενημέρωση, μαζί με την προεπιλογή του — άφησέ το κενό και η δραστηριότητα μετονομάζεται στο εφεδρικό όνομα εκείνου του endpoint.
Τα μπλοκ ρυθμίσεων που γράφει το ίδιο το endpoint ξαναγράφονται από την αρχή, οπότε μια ενημέρωση τα επαναφέρει κι αυτά στις τιμές που στέλνεις ή στις προεπιλογές του endpoint.
Μπορείς να ενημερώσεις μόνο δραστηριότητες που ανήκουν στον δικό σου λογαριασμό. Το κλειδί κάποιου άλλου απαντά 403.
Μια ενημέρωση κοστίζει όσο και μια δημιουργία: μία κλήση από το σημερινό όριο.

Όριο κλήσεων

10 δραστηριότητες ανά λογαριασμό την ημέρα

Κάθε επιτυχημένη κλήση μετράει, δημιουργίες και ενημερώσεις το ίδιο. Αν το ξεπεράσεις, το επόμενο αίτημα απαντά 429 μέχρι να μηδενιστεί ο μετρητής.

Ο μετρητής μηδενίζεται μία φορά την ημέρα από μια προγραμματισμένη εργασία, όχι με κυλιόμενο παράθυρο 24 ωρών.

Σφάλματα

Τα σφάλματα έρχονται πάντα ως JSON με τα ίδια δύο πεδία, ποτέ ως σελίδα HTML. Το string του σφάλματος είναι γραμμένο για να το διαβάσει άνθρωπος — ονομάζει το πεδίο ή το όριο που απέτυχε.

Κατάσταση	Τι σημαίνει
`400` Bad Request	Κάτι στο σώμα λείπει, είναι λάθος διατυπωμένο ή εκτός ορίων. Το μήνυμα ονομάζει το πεδίο.
`401` Unauthorized	Το email είναι άγνωστο ή το κλειδί δεν ανήκει σε αυτόν τον λογαριασμό.
`403` Forbidden	Το activity_key που έστειλες ανήκει σε άλλον λογαριασμό.
`429` Too Many Requests	Το σημερινό όριο εξαντλήθηκε. Μηδενίζεται μία φορά την ημέρα.
`500` Server Error	Η γεννήτρια δεν μπόρεσε να δημιουργήσει γρίφο από αυτά που έστειλες — συνήθως πολύ λίγες λέξεις ή λέξεις που δεν ταιριάζουν μεταξύ τους.

Endpoints

Μία διαδρομή ανά τύπο δραστηριότητας, όλες POST, όλες κάτω από το ίδιο βασικό URL. Καθεμιά αναφέρει το περιεχόμενο που χρειάζεται, τις ρυθμίσεις που διαβάζει και ένα αίτημα που μπορείς να τρέξεις.

Λέξεις και γράμματα

Σταυρόλεξο

Πλέκει τις απαντήσεις σου σε ένα πλέγμα και αριθμεί τους ορισμούς για σένα.

POST /api/public/v1/crossword Τουλάχιστον 2 στο items

Περιεχόμενο

Ένας πίνακας λέξεων. Κάθε εγγραφή συνδυάζει την απάντηση με τον ορισμό που δείχνει προς αυτήν.

Πέφτει πίσω στο όνομα “Crossword API”

Καλό είναι να ξέρεις

Οι απαντήσεις με λιγότερους από δύο χαρακτήρες αφαιρούνται πριν δημιουργηθεί το πλέγμα, και πρέπει να μείνουν τουλάχιστον δύο.
Οι απαντήσεις μετατρέπονται σε κεφαλαία και η γεννήτρια έχει είκοσι προσπάθειες να τις τοποθετήσει. Αν δεν καταφέρει να τοποθετήσει ούτε μία λέξη, η κλήση απαντά 500.

Παράδειγμα αιτήματος

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": "gr",
  "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"
    }
  ]
}'

Επιτυχία

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

Πεδίο	Τύπος	Τι κάνει
`hidden_solution` προαιρετικό στο settings string	string	Τα γράμματα που περισσεύουν σχηματίζουν αυτό. Αν το ορίσεις, η γεννήτρια τοποθετεί πρώτα τη λύση αντί να στριμώξει όσες περισσότερες λέξεις μπορεί.
`directions` προαιρετικό στο settings string[]	string[]	Προς ποιες κατευθύνσεις επιτρέπεται να τρέχει μια λέξη. Άφησέ το κενό και οι λέξεις τρέχουν μόνο ανατολικά, νοτιοανατολικά και νότια. Ένα από `westeastnorthsouthnorthwestnortheastsouthwestsoutheast` Προεπιλογή: ["east", "southeast", "south"]
`template` προαιρετικό στο settings string	string	Κόβει το πλέγμα σε ένα σχήμα αντί να το αφήνει τετράγωνο. Ένα από `squarecirclecrossdiamondpyramidsmileystarcross_plus`

Πεδίο	Τύπος	Τι κάνει
`number_of_tiles` προαιρετικό στο settings number	number	Πόσα τετράγωνα έχει το ταμπλό. Από 10 έως 75. Προεπιλογή: 30
`game_mode` προαιρετικό στο settings string	string	Αν οι παίκτες τρέχουν προς τον τερματισμό ή μαζεύουν αντικείμενα στον δρόμο. Ένα από `race_to_finishcollect_items` Προεπιλογή: "race_to_finish"

Πεδίο	Τύπος	Τι κάνει
`sentence` υποχρεωτικό string	string	Η πρόταση που θα κρυπτογραφηθεί. Οι παίκτες την αποκωδικοποιούν χαρακτήρα προς χαρακτήρα.
`helpers` προαιρετικό στο settings string	string	Ποιοι χαρακτήρες δίνονται δωρεάν ως βοήθεια για την αρχή: κανένας, οι πιο συχνοί, τα φωνήεντα ή όσοι ορίσεις εσύ. Ένα από `nonemost_commonvowelscustom` Προεπιλογή: "none"
`character_list` προαιρετικό στο settings string	string	Το αλφάβητο από το οποίο δημιουργείται ο κώδικας. Αν μείνει κενό, η κρυπτογράφηση διαλέγει μόνη της.
`extra_letters` προαιρετικό στο settings string	string	Οι χαρακτήρες που δίνονται όταν το helpers είναι "custom". Αγνοείται στις άλλες λειτουργίες βοήθειας.
`hide_unused_characters` προαιρετικό στο settings boolean	boolean	Αφήνει έξω από το κλειδί τους χαρακτήρες που δεν χρησιμοποιεί πουθενά η πρόταση. Προεπιλογή: false

Πεδίο	Τύπος	Τι κάνει
`sentence` υποχρεωτικό string	string	Η πρόταση που αποκαλύπτουν οι παίκτες λύνοντας τις πράξεις.
`difficulty_level` προαιρετικό στο settings number	number	Το μεγαλύτερο αποτέλεσμα που επιτρέπεται να έχει μια πράξη. Ένα από `20501001000` Προεπιλογή: "100"
`operators` προαιρετικό στο settings string[]	string[]	Ποιες πράξεις μπορούν να εμφανιστούν. Το x είναι πολλαπλασιασμός, το : διαίρεση. Ένα από `+-x:` Προεπιλογή: ["+", "-", "x", ":"]
`max_operations` προαιρετικό στο settings number	number	Πόσες πράξεις μπορεί να συνδυάσει μία άσκηση. Ένα από `123` Προεπιλογή: 1
`number_difficulty` προαιρετικό στο settings number	number	Περιορίζει τους μεμονωμένους αριθμούς μέσα σε μια πράξη. Από 5 έως 1000. Προεπιλογή: 100

Πεδίο	Τύπος	Τι κάνει
`size` προαιρετικό στο settings string	string	Το μέγεθος ενός μπλοκ, γραμμένο ως γραμμές επί στήλες — το 3x3 δίνει το κλασικό πλέγμα 9x9. Το endpoint ελέγχει μόνο ότι διαβάζεται ως δύο αριθμοί, γι' αυτό μείνε στα μεγέθη που προσφέρει ο επεξεργαστής. Ένα από `2x22x33x33x44x4` Προεπιλογή: "3x3"
`difficulty_level` προαιρετικό στο settings string	string	Πόσοι αριθμοί μένουν στο πλέγμα για να ξεκινήσεις. Ένα από `easynormalhard` Προεπιλογή: "normal"

Δημιούργησε δραστηριότητες από το δικό σου σύστημα

Το πρώτο σου αίτημα

Έλεγχος ταυτότητας

Το σώμα του αιτήματος

Τι παίρνεις πίσω

Δημιουργία ή ενημέρωση

Όριο κλήσεων

Σφάλματα

Endpoints

Κάτι δεν δουλεύει σωστά;