Επισκόπηση API

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

Βασικό URL

https://api-eu1.joryio.com

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

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

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

GET /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

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

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

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

Συλλογή Postman

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

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

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

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

POST /users
Content-Type: application/json

{
  "userId": "user_123",
  "email": "user@example.com",
  "attributes": {
    "plan": "premium"
  }
}

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

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

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

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

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "email": "user@example.com",
  "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": "/events/track",
  "errors": [
    "eventName must be shorter than or equal to 500 characters"
  ]
}

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

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

Όρια ρυθμού

Τα βασικά endpoints του API (χρήστες, συμβάντα, τμήματα, καμπάνιες) δεν επιβάλλουν σήμερα σταθερά όρια ρυθμού ανά endpoint. Ο περιορισμός (throttling) εφαρμόζεται σε επιφάνειες επιρρεπείς σε κατάχρηση - endpoints ελέγχου ταυτότητας και δέκτες εισερχόμενων webhooks - με σταθερά παράθυρα ανά λεπτό.

Όταν ένα αίτημα περιοριστεί, το API απαντά 429 Too Many Requests με κεφαλίδα Retry-After (δευτερόλεπτα μέχρι την επαναφορά του παραθύρου):

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 είναι upsert με κλειδί το δικό σας userId - η επανάληψη του ίδιου αιτήματος ενημερώνει το ίδιο προφίλ αντί να δημιουργήσει διπλότυπο.
• Το POST /events/track δέχεται προαιρετικό 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	Δημιουργία ή ενημέρωση ενός χρήστη (σώμα-αντικείμενο) ή πολλών (σώμα-σκέτος πίνακας, μέγιστο 1000)
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	/events/track	Καταγραφή ενός συμβάντος (σώμα-αντικείμενο) ή πολλών (σώμα-σκέτος πίνακας, μέγιστο 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/users \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "email": "user@example.com",
    "attributes": {
      "firstName": "John",
      "lastName": "Doe",
      "plan": "premium"
    }
  }'

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

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

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

curl -X POST https://api-eu1.joryio.com/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/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) είναι ενσωματωμένες στους επεξεργαστές καμπανιών.

Υποστήριξη

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

• Πλήρης αναφορά API
• Τεκμηρίωση προγραμματιστών
• Email: support@joryio.com