Επισκόπηση API

Το REST API του Joryio παρέχει προγραμματιστική πρόσβαση σε όλες τις δυνατότητες της πλατφόρμας.

Βασικό URL

https://api-eu1.joryio.com/api

Όλοι οι χώροι εργασίας εξυπηρετούνται προς το παρόν από μία μόνο περιοχή· τα endpoints ανά περιοχή θα τεκμηριωθούν όταν κυκλοφορήσουν επιπλέον περιοχές.

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

Όλα τα αιτήματα API απαιτούν έλεγχο ταυτότητας μέσω κλειδιού API. Τα κλειδιά ισχύουν για έναν μόνο χώρο εργασίας, φέρουν ένα ρητό σύνολο δικαιωμάτων και μπορούν να περιοριστούν σε μια λίστα IP. Δείτε την αναφορά Κλειδιά API για τον πλήρη κατάλογο scopes και τη συμπεριφορά της λίστας επιτρεπόμενων IP.

GET /api/users/by-user-id/user_123
Host: api-eu1.joryio.com
Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

Στείλτε το κλειδί ως bearer token στην κεφαλίδα Authorization σε κάθε αίτημα. Τα κλειδιά ξεκινούν πάντα με jry_live_ (παραγωγή) ή jry_test_ (δοκιμές). Το ορατό πρόθεμα του κλειδιού (π.χ. jry_live_98f31a72) είναι ασφαλές για καταγραφή σε logs - το υπόλοιπο είναι μυστικό.

Λήψη του κλειδιού API

Συνδεθείτε στο dashboard του Joryio.
Μεταβείτε στις Ρυθμίσεις → Κλειδιά API.
Κάντε κλικ στη Δημιουργία κλειδιού API, επιλέξτε τα scopes που χρειάζεται η ενσωμάτωση και αντιγράψτε την τιμή που εμφανίζεται μία μόνο φορά.

Κρατήστε τα κλειδιά API μυστικά

Μην κάνετε ποτέ commit κλειδιά API σε σύστημα ελέγχου εκδόσεων και μην τα εκθέτετε σε κώδικα πλευράς πελάτη. Η πλήρης τιμή εμφανίζεται ακριβώς μία φορά μετά τη δημιουργία - αποθηκεύστε την αμέσως στον διαχειριστή μυστικών σας.

Συλλογή Postman

Ο ταχύτερος τρόπος να εξερευνήσετε το API: εισαγάγετε την επίσημη συλλογή στο Postman - κάθε δημόσιο endpoint με παράδειγμα σώματος, προ-συνδεδεμένο με τη μεταβλητή {{baseUrl}} και έλεγχο ταυτότητας bearer token.

Κατεβάστε τη συλλογή
Στο Postman: Import → σύρετε το αρχείο μέσα.
Ορίστε τις μεταβλητές της συλλογής: baseUrl = https://api-eu1.joryio.com/api, token = το κλειδί API σας (jry_live_...).

Μορφή αιτήματος

Όλα τα αιτήματα και οι αποκρίσεις χρησιμοποιούν JSON:

POST /users/track
Content-Type: application/json

{
  "attributes": {
    "externalId": "user_123",
    "email": "[email protected]",
    "attributes": {
      "plan": "premium"
    }
  }
}

Μορφή απόκρισης

Τα endpoints επιστρέφουν απευθείας το JSON του πόρου - δεν υπάρχει περιτύλιγμα-φάκελος { "success": true, "data": ... }.

Απόκριση επιτυχίας

Για παράδειγμα, το GET /users/by-user-id/user_123 επιστρέφει το ίδιο το αντικείμενο χρήστη:

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "email": "[email protected]",
  "phone": "+14155550123",
  "attributes": { "plan": "premium" },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

Τα id / userId είναι το εσωτερικό αναγνωριστικό του Joryio· το αναγνωριστικό που δώσατε επιστρέφεται ως externalId.

Απόκριση σφάλματος

Όλα τα σφάλματα μοιράζονται μία μορφή, που παράγεται από ένα καθολικό φίλτρο εξαιρέσεων:

{
  "statusCode": 400,
  "message": "Cannot create user without a valid identifier (userId, externalId, or email)",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/users"
}

Οι αποτυχίες επικύρωσης αιτήματος (400) φέρουν επιπλέον έναν πίνακα errors με ένα μήνυμα ανά πεδίο που απέτυχε:

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/api/users/track",
  "errors": [
    "eventName must be shorter than or equal to 500 characters"
  ]
}

Σφάλματα στο σώμα του αιτήματος

Ένα σώμα που ο διακομιστής δεν μπορεί να διαβάσει απορρίπτεται πριν φτάσει στο endpoint, με ένα message που ονομάζει το πρόβλημα. Το σώμα που στείλατε δεν επιστρέφεται ποτέ στην απόκριση.

Κατάσταση	`message`	Αιτία
`400`	`Request body is not valid JSON.`	Το JSON έχει συντακτικό σφάλμα.
`400`	`Request body must be a JSON object or array - a bare string, number, boolean or null is not accepted.`	Το ανώτερο επίπεδο δεν είναι αντικείμενο `{...}` ή πίνακας `[...]`.
`413`	`Request body is too large - the limit is 1 MB.`	Το σώμα ξεπερνά το 1 MB.
`415`	`Request body charset is not supported - send UTF-8.`	Το `Content-Type` δηλώνει charset διαφορετικό από UTF-8.

Κωδικοί κατάστασης HTTP

Κωδικός	Σημασία	Περιγραφή
`200`	OK	Το αίτημα ολοκληρώθηκε επιτυχώς
`201`	Created	Ο πόρος δημιουργήθηκε επιτυχώς
`204`	No Content	Η διαγραφή ολοκληρώθηκε (κενό σώμα απόκρισης)
`400`	Bad Request	Μη έγκυρες παράμετροι αιτήματος
`401`	Unauthorized	Μη έγκυρο κλειδί API ή κλειδί που λείπει
`403`	Forbidden	Το κλειδί API δεν έχει τα απαιτούμενα δικαιώματα
`404`	Not Found	Ο πόρος δεν βρέθηκε
`409`	Conflict	Ο πόρος υπάρχει ήδη
`413`	Payload Too Large	Σώμα αιτήματος μεγαλύτερο από 1 MB
`415`	Unsupported Media Type	Μη υποστηριζόμενο charset ή κωδικοποίηση σώματος
`429`	Too Many Requests	Υπέρβαση ορίου ρυθμού
`500`	Internal Server Error	Προέκυψε σφάλμα διακομιστή
`503`	Service Unavailable	Η υπηρεσία δεν είναι προσωρινά διαθέσιμη

Όρια ρυθμού

Τα endpoints του API με έλεγχο ταυτότητας εφαρμόζουν ένα όριο ανά οργανισμό. Πρόκειται για όριο κατάχρησης, όχι για προϋπολογισμό ρυθμού: βρίσκονται πολύ πάνω από τη φυσιολογική χρήση, και η χωρητικότητα αντιμετωπίζεται από τον στόλο των workers μας, όχι με απόρριψη αιτημάτων στο άκρο.

Επιφάνεια	Όριο	Με βάση
Αιτήματα API	1.200/λεπτό	τον οργανισμό σας
Εισαγωγή επαφών και συμβάντων (`POST /users/track`)	6.000/λεπτό	τον οργανισμό σας
Σύνδεση και επαναφορά κωδικού	5-10/λεπτό	διεύθυνση IP

Τα όρια με έλεγχο ταυτότητας βασίζονται στον οργανισμό σας, όχι στην IP: έτσι ένας στόλος διακομιστών μοιράζεται έναν προϋπολογισμό αντί να έχει ο καθένας τον δικό του, και δύο πελάτες πίσω από το ίδιο δίκτυο δεν επηρεάζουν ποτέ ο ένας τον άλλον.

Τα τρέχοντα όρια του λογαριασμού σας εμφανίζονται στις Ρυθμίσεις -> Χρήση και μπορούν να αυξηθούν. Αν μια μαζική εισαγωγή πλησιάζει κάποιο όριο, επικοινωνήστε στο [email protected].

Οι δέκτες εισερχόμενων webhook - συμβάντα παράδοσης, απαντήσεις, callbacks πλατφορμών ecommerce - είναι σκόπιμα χωρίς όριο. Ένα απορριφθέν webhook είναι απώλεια δεδομένων, οπότε αυτά τα endpoints προστατεύονται με επαλήθευση υπογραφής αντί για μετρητή.

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1188
X-RateLimit-Reset: 60

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/auth/login"
}

Διαχείριση ορίων ρυθμού

Τα όρια μπορεί να εισαχθούν ή να γίνουν αυστηρότερα με τον χρόνο - αντιμετωπίζετε πάντα το 429 ως επαναλήψιμο, τηρείτε το Retry-After και υλοποιήστε εκθετική αναμονή (exponential backoff):

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }
}

Σελιδοποίηση

Τα endpoints λιστών σελιδοποιούν με παραμέτρους query limit / offset:

GET /users?limit=50&offset=100

Παράμετροι:

limit: Αποτελέσματα ανά σελίδα (οι προεπιλογές και τα μέγιστα διαφέρουν ανά endpoint - χρήστες: προεπιλογή 50, μέγιστο 200· τμήματα: προεπιλογή 100, μέγιστο 100· query συμβάντων: προεπιλογή 100, μέγιστο 1000)
offset: Πλήθος στοιχείων που παραλείπονται (προεπιλογή: 0)

Απόκριση:

Οι σελιδοποιημένες αποκρίσεις λιστών τυλίγουν τη σελίδα σε έναν πίνακα data και ένα αντικείμενο pagination:

{
  "data": [...],
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 100,
    "hasMore": true
  }
}

Ορισμένα endpoints περιλαμβάνουν επιπλέον πεδία σελιδοποίησης (όπως page / totalPages), και ορισμένες μικρότερες λίστες επιστρέφουν σκέτο πίνακα JSON - η σελίδα κάθε endpoint τεκμηριώνει την ακριβή μορφή του.

Φιλτράρισμα

Δεν υπάρχει γενική σύνταξη query filter[field] ή sort. Τα endpoints λιστών εκθέτουν αντ' αυτού παραμέτρους φίλτρων ειδικές ανά endpoint, για παράδειγμα:

GET /events/query?eventName=Order+Completed&startDate=2026-01-01&endDate=2026-01-31
GET /segments?q=vip&status=active&tags=onboarding
GET /users/search?query=jane

Τα αποτελέσματα επιστρέφονται σε σταθερή σειρά, με τα πιο πρόσφατα πρώτα.

Idempotency

Δεν υπάρχει γενική κεφαλίδα αιτήματος Idempotency-Key. Η ασφάλεια επαναλήψεων παρέχεται ανά endpoint:

Το POST /users/track είναι upsert με κλειδί το δικό σας externalId - η επανάληψη του ίδιου αιτήματος ενημερώνει το ίδιο προφίλ αντί να δημιουργήσει διπλότυπο.
Κάθε στοιχείο του events δέχεται προαιρετικό clientEventId· χρησιμοποιείται ως το αποθηκευμένο ID συμβάντος, οπότε ένα επαναληφθέν αίτημα με το ίδιο clientEventId απαλείφεται ως διπλότυπο.
Το POST /campaigns/transactional/send δέχεται προαιρετικό idempotencyKey στο σώμα - μια επανάληψη με το ίδιο κλειδί δεν θα στείλει δύο φορές.

Χρονοσφραγίδες

Όλες οι χρονοσφραγίδες είναι σε μορφή ISO 8601 με ζώνη ώρας UTC:

{
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T14:45:30.000Z"
}

Endpoints του API

Users API

Μέθοδος	Endpoint	Περιγραφή
POST	`/users/track`	Δημιουργία ή ενημέρωση ατόμων και καταγραφή των συμβάντων, των αγορών και των συσκευών push τους - κάθε πεδίο δέχεται ένα αντικείμενο ή πίνακα (μέγιστο 1000 `attributes` ανά αίτημα)
GET	`/users`	Λίστα χρηστών (`limit` / `offset`)
GET	`/users/search`	Αναζήτηση χρηστών βάσει email, ονόματος, τηλεφώνου ή ID
GET	`/users/:userId`	Λήψη χρήστη βάσει εσωτερικού ID του Joryio
GET	`/users/by-user-id/:userId`	Λήψη χρήστη βάσει του δικού σας `userId`
PUT	`/users/:userId`	Ενημέρωση χρήστη βάσει εσωτερικού ID
PUT	`/users/by-user-id/:userId`	Ενημέρωση χρήστη βάσει του δικού σας `userId`
DELETE	`/users/:userId`	Διαγραφή χρήστη (επιστρέφει `204`)

Events API

Μέθοδος	Endpoint	Περιγραφή
POST	`/users/track`	Καταγραφή ενός ή πολλών συμβάντων - το `events` δέχεται ένα αντικείμενο ή πίνακα (μέγιστο 500 ανά αίτημα)
GET	`/events/query`	Ερώτημα συμβάντων με φίλτρα
POST	`/events/aggregate`	Συγκεντρωτικές μετρήσεις συμβάντων στον χρόνο

Campaigns API

Μέθοδος	Endpoint	Περιγραφή
POST	`/campaigns`	Δημιουργία καμπάνιας
GET	`/campaigns/:id`	Λήψη καμπάνιας
PUT	`/campaigns/:id`	Ενημέρωση καμπάνιας
DELETE	`/campaigns/:id`	Διαγραφή καμπάνιας
POST	`/campaigns/:id/send`	Αποστολή καμπάνιας
GET	`/campaigns/:id/stats`	Λήψη στατιστικών καμπάνιας

Segments API

Μέθοδος	Endpoint	Περιγραφή
POST	`/segments`	Δημιουργία τμήματος
GET	`/segments`	Λίστα τμημάτων
GET	`/segments/:id`	Λήψη τμήματος
PUT	`/segments/:id`	Ενημέρωση τμήματος
POST	`/segments/:id/archive`	Αρχειοθέτηση τμήματος (τα τμήματα δεν διαγράφονται οριστικά)
GET	`/segments/:id/users`	Λήψη χρηστών τμήματος
GET	`/segments/:id/size`	Λήψη μεγέθους τμήματος

Apps API

Μέθοδος	Endpoint	Περιγραφή
POST	`/apps`	Δημιουργία εφαρμογής
GET	`/apps/:id`	Λήψη εφαρμογής
PUT	`/apps/:id`	Ενημέρωση εφαρμογής
DELETE	`/apps/:id`	Διαγραφή εφαρμογής
POST	`/apps/:id/regenerate-key`	Αναδημιουργία κλειδιού SDK
GET	`/apps/:id/stats`	Λήψη στατιστικών εφαρμογής

SDKs

Για ευκολότερη ενσωμάτωση, χρησιμοποιήστε τα επίσημα SDK μας:

Web SDK: npm install @joryio/web-sdk
iOS SDK: Swift Package / CocoaPods
Android SDK: Gradle
React Native SDK: npm install @joryio/react-native-sdk

Παραδείγματα

Δημιουργία χρήστη

curl -X POST https://api-eu1.joryio.com/api/users/track \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "externalId": "user_123",
      "email": "[email protected]",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe",
        "plan": "premium"
      }
    }
  }'

Καταγραφή συμβάντος

curl -X POST https://api-eu1.joryio.com/api/users/track \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": {
      "externalId": "user_123",
      "name": "Order Completed",
      "properties": { "orderId": "order_456", "total": 99.99 }
    }
  }'

Δημιουργία τμήματος

curl -X POST https://api-eu1.joryio.com/api/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Users",
    "description": "Users on premium plan",
    "filterGroups": [{
      "filters": [{
        "type": "attribute",
        "field": "plan",
        "operator": "equals",
        "value": "premium"
      }],
      "operator": "AND"
    }],
    "groupOperator": "AND"
  }'

Αποστολή καμπάνιας

Το endpoint αποστολής δεν παίρνει σώμα αιτήματος - η αποθηκευμένη ρύθμιση της καμπάνιας καθορίζει τι αποστέλλεται:

curl -X POST https://api-eu1.joryio.com/api/campaigns/:id/send \
  -H "Authorization: Bearer jry_live_your_api_key"

Σφάλματα

Δεν υπάρχει ξεχωριστό μηχαναγνώσιμο λεξιλόγιο κωδικών σφαλμάτων - χρησιμοποιήστε τον κωδικό κατάστασης HTTP μαζί με το πεδίο message του τυπικού σώματος σφάλματος (δείτε Μορφή απόκρισης):

{
  "statusCode": 404,
  "message": "Segment with ID 3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d not found",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d"
}

Δοκιμές

Τα κλειδιά μπορούν να δημιουργηθούν με ετικέτα test (jry_test_...), ώστε να ξεχωρίζετε με μια ματιά τα κλειδιά ενσωμάτωσης από τα κλειδιά παραγωγής - η ετικέτα δεν αλλάζει τι μπορεί να κάνει το κλειδί. Για ασφαλή πειραματισμό, δημιουργήστε έναν ξεχωριστό χώρο εργασίας για δοκιμές: οι χώροι εργασίας απομονώνουν πλήρως προφίλ, συμβάντα και καμπάνιες, οπότε τίποτα από όσα δοκιμάσετε δεν μπορεί να αγγίξει δεδομένα ή παραλήπτες παραγωγής. Οι δοκιμαστικές αποστολές ανά κανάλι (δοκιμαστικά email, δοκιμαστικά SMS) είναι ενσωματωμένες στους επεξεργαστές καμπανιών.

Υποστήριξη

Χρειάζεστε βοήθεια;

Βασικό URL​

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

Λήψη του κλειδιού API​

Συλλογή Postman​

Μορφή αιτήματος​

Μορφή απόκρισης​

Απόκριση επιτυχίας​

Απόκριση σφάλματος​

Σφάλματα στο σώμα του αιτήματος​

Κωδικοί κατάστασης HTTP​

Όρια ρυθμού​

Διαχείριση ορίων ρυθμού​

Σελιδοποίηση​

Φιλτράρισμα​

Idempotency​

Χρονοσφραγίδες​

Endpoints του API​

Users API​

Events API​

Campaigns API​

Segments API​

Apps API​

SDKs​

Παραδείγματα​

Δημιουργία χρήστη​

Καταγραφή συμβάντος​

Δημιουργία τμήματος​

Αποστολή καμπάνιας​

Σφάλματα​

Δοκιμές​

Υποστήριξη​