Μετάβαση στο κύριο περιεχόμενο

Segments API

Δημιουργήστε και διαχειριστείτε δυναμικά τμήματα χρηστών προγραμματιστικά.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com - δείτε Επισκόπηση API.

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

Όλα τα αιτήματα απαιτούν έλεγχο ταυτότητας με κλειδί API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

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

Δημιουργήστε ένα νέο τμήμα χρηστών με φίλτρα.

Endpoint

POST /segments

Σώμα αιτήματος

ΠεδίοΤύποςΑπαιτείταιΠεριγραφή
namestringΝαιΌνομα τμήματος (μέγιστο 255 χαρακτήρες)
descriptionstringΌχιΠεριγραφή τμήματος (μέγιστο 1000 χαρακτήρες)
filterGroupsarrayΝαιΠίνακας ομάδων φίλτρων (μέγιστο 20)
excludeFilterGroupsarrayΌχιΟι χρήστες που ταιριάζουν σε οποιαδήποτε από αυτές τις ομάδες αφαιρούνται (μέγιστο 20)
groupOperatorstringΝαιΠώς συνδυάζονται οι ομάδες: AND ή OR
tagsarrayΌχιΟνόματα ετικετών για την οργάνωση τμημάτων

Δομή φίλτρων

Κάθε ομάδα φίλτρων περιέχει έως 50 φίλτρα:

{
filters: [
{
type: 'attribute' | 'default_attribute' | 'event' | 'ecommerce'
| 'behavioral' | 'segment' | 'canvas_execution'
| 'list_membership' | 'channel_subscription' | 'app'
| 'entity' | 'bounce_status' | 'wallet_pass',
field?: string, // For attribute filters
operator: string, // See Filter Operators below
value?: any, // Comparison value (also carries N for count operators)
eventName?: string, // For event filters
withinDays?: number, // Time window for event filters
startDate?: string, // Absolute window start (ISO 8601, event filters)
endDate?: string, // Absolute window end (ISO 8601, event filters)
segmentId?: string, // For segment filters
listId?: string, // For list_membership filters
channel?: string // For channel_subscription filters
}
],
operator: 'AND' | 'OR'
}

Παράδειγμα αιτήματος - Απλό φίλτρο γνωρίσματος

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"
}'

Παράδειγμα αιτήματος - Τμήμα συμπεριφοράς

curl -X POST https://api-eu1.joryio.com/segments \
-H "Authorization: Bearer jry_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Active Trial Users",
"description": "Trial users active in last 7 days",
"filterGroups": [
{
"filters": [
{
"type": "attribute",
"field": "plan",
"operator": "equals",
"value": "trial"
},
{
"type": "event",
"eventName": "Session Started",
"operator": "performed",
"withinDays": 7
}
],
"operator": "AND"
}
],
"groupOperator": "AND"
}'

Παράδειγμα αιτήματος - Σύνθετο τμήμα

curl -X POST https://api-eu1.joryio.com/segments \
-H "Authorization: Bearer jry_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "High-Value At-Risk Users",
"description": "Paid users with high LTV who haven'\''t logged in recently",
"filterGroups": [
{
"filters": [
{
"type": "attribute",
"field": "plan",
"operator": "in",
"value": ["premium", "enterprise"]
},
{
"type": "attribute",
"field": "lifetimeValue",
"operator": "gte",
"value": 500
}
],
"operator": "AND"
},
{
"filters": [
{
"type": "event",
"eventName": "Login",
"operator": "not_performed",
"withinDays": 14
}
],
"operator": "AND"
}
],
"groupOperator": "AND"
}'

Απόκριση

Το αντικείμενο του τμήματος επιστρέφεται απευθείας (χωρίς περιτύλιγμα-φάκελο). Τα IDs τμημάτων είναι UUID. Το πλήθος μελών δεν αποθηκεύεται στο τμήμα - χρησιμοποιήστε το GET /segments/:id/size:

{
"id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
"name": "Premium Users",
"description": "Users on premium plan",
"filterGroups": [
{
"filters": [
{
"type": "attribute",
"field": "plan",
"operator": "equals",
"value": "premium"
}
],
"operator": "AND"
}
],
"excludeFilterGroups": [],
"groupOperator": "AND",
"tags": [],
"status": "active",
"createdAt": "2024-01-20T10:30:00.000Z",
"updatedAt": "2024-01-20T10:30:00.000Z"
}

Λήψη τμήματος

Ανάκτηση των λεπτομερειών ενός τμήματος.

Endpoint

GET /segments/:id

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

ΠαράμετροςΤύποςΠεριγραφή
idstringID τμήματος

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

curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
-H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Το αντικείμενο του τμήματος, επιστρεφόμενο απευθείας (για το τρέχον πλήθος μελών, καλέστε το GET /segments/:id/size):

{
"id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
"name": "Premium Users",
"description": "Users on premium plan",
"filterGroups": [...],
"excludeFilterGroups": [],
"groupOperator": "AND",
"tags": [],
"status": "active",
"createdAt": "2024-01-20T10:30:00.000Z",
"updatedAt": "2024-01-20T10:30:00.000Z"
}

Λίστα τμημάτων

Λήψη όλων των τμημάτων με σελιδοποίηση.

Endpoint

GET /segments

Παράμετροι query

ΠαράμετροςΤύποςΠροεπιλογήΠεριγραφή
limitnumber100Αποτελέσματα ανά σελίδα (μέγιστο 100)
offsetnumber0Πλήθος τμημάτων που παραλείπονται
qstring-Αναζήτηση ελεύθερου κειμένου στο όνομα του τμήματος
statusstring-Φιλτράρισμα βάσει κατάστασης: active ή archived
tagsstring-Ονόματα ετικετών χωρισμένα με κόμμα
createdBystring-IDs χρηστών-δημιουργών χωρισμένα με κόμμα
editedBystring-IDs χρηστών-τελευταίων συντακτών χωρισμένα με κόμμα

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

curl -X GET "https://api-eu1.joryio.com/segments?limit=50&status=active" \
-H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
"data": [
{
"id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
"name": "Premium Users",
"status": "active",
"createdAt": "2024-01-20T10:30:00.000Z"
},
{
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Trial Users",
"status": "active",
"createdAt": "2024-01-19T09:15:00.000Z"
}
],
"pagination": {
"total": 23,
"page": 1,
"limit": 50,
"offset": 0,
"totalPages": 1,
"hasMore": false
}
}

Ενημέρωση τμήματος

Ενημερώστε το όνομα, την περιγραφή ή τα φίλτρα του τμήματος. Χρησιμοποιεί PUT (δεν υπάρχει διαδρομή PATCH)· τα πεδία που παραλείπετε μένουν αμετάβλητα.

Endpoint

PUT /segments/:id

Σώμα αιτήματος

{
"name": "Updated Name",
"description": "Updated description",
"filterGroups": [...]
}

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

curl -X PUT https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
-H "Authorization: Bearer jry_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"description": "Premium users who have made at least one purchase"
}'

Απόκριση

Το ενημερωμένο αντικείμενο του τμήματος, επιστρεφόμενο απευθείας:

{
"id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
"name": "Premium Users",
"description": "Premium users who have made at least one purchase",
"status": "active",
"updatedAt": "2024-01-21T14:30:00.000Z"
}

Αρχειοθέτηση τμήματος

Τα τμήματα δεν μπορούν να διαγραφούν οριστικά - καμπάνιες και journeys διατηρούν αναφορές σε τμήματα, οπότε η αφαίρεση γίνεται μόνο με αρχειοθέτηση. Τα αρχειοθετημένα τμήματα παύουν να εμφανίζονται στις ενεργές λίστες και μπορούν να επαναφερθούν οποιαδήποτε στιγμή.

Endpoints

POST /segments/:id/archive
POST /segments/:id/unarchive

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

curl -X POST https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/archive \
-H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Το αντικείμενο του τμήματος με τη νέα του κατάσταση:

{
"id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
"name": "Premium Users",
"status": "archived",
"updatedAt": "2024-01-21T14:30:00.000Z"
}

Σημειώσεις

  • Η αρχειοθέτηση ενός τμήματος δεν διαγράφει τους χρήστες του
  • Οι ενεργές καμπάνιες που χρησιμοποιούν αυτό το τμήμα θα επηρεαστούν
  • Χρησιμοποιήστε POST /segments/:id/unarchive για επαναφορά

Λήψη χρηστών τμήματος

Λήψη της λίστας χρηστών ενός τμήματος.

Endpoint

GET /segments/:id/users

Παράμετροι query

ΠαράμετροςΤύποςΠροεπιλογήΠεριγραφή
limitnumber100Πλήθος χρηστών που επιστρέφονται
offsetnumber0Πλήθος χρηστών που παραλείπονται

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

curl -X GET "https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/users?limit=100" \
-H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Ένας σκέτος πίνακας JSON με έγγραφα χρηστών (χωρίς φάκελο σελιδοποίησης - σελιδοποιήστε με limit / offset):

[
{
"_id": "665f1e2a9b3c4d5e6f7a8b9c",
"externalId": "user_123",
"email": "user1@example.com",
"attributes": {
"plan": "premium",
"signupDate": "2024-01-15"
}
},
{
"_id": "665f1e2a9b3c4d5e6f7a8b9d",
"externalId": "user_456",
"email": "user2@example.com",
"attributes": {
"plan": "premium",
"signupDate": "2024-01-18"
}
}
]

Λήψη μεγέθους τμήματος

Λήψη του τρέχοντος πλήθους χρηστών ενός τμήματος. Από προεπιλογή είναι μια γρήγορη προσεγγιστική εκτίμηση· περάστε ?exact=true για ακριβή μέτρηση. Το μόνο που είναι ποτέ προσεγγιστικό είναι ο αριθμός του μεγέθους - η πραγματική συμμετοχή και οι αποστολές είναι πάντα ακριβείς.

Endpoint

GET /segments/:id/size

Παράμετροι query

ΠαράμετροςΤύποςΠροεπιλογήΠεριγραφή
exactbooleanfalseΜε true επιστρέφεται η ακριβής μέτρηση (πιο αργή σε μεγάλους χώρους εργασίας)

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

curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
-H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
"segmentId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
"size": 1234,
"approximate": true
}

Τελεστές φίλτρων

Τελεστές γνωρισμάτων

ΤελεστήςΠεριγραφήΠαράδειγμα
equalsΑκριβής αντιστοίχισηplan equals "premium"
not_equalsΔιάφοροplan not_equals "free"
inΤιμή μέσα σε λίσταplan in ["premium", "enterprise"]
not_inΤιμή εκτός λίσταςplan not_in ["free", "trial"]
containsΗ συμβολοσειρά περιέχειemail contains "@company.com"
not_containsΗ συμβολοσειρά δεν περιέχειemail not_contains "@competitor.com"
gtΜεγαλύτερο απόlifetimeValue > 1000
gteΜεγαλύτερο ή ίσοage >= 18
ltΜικρότερο απόloginCount < 5
lteΜικρότερο ή ίσοmrr <= 99
existsΤο πεδίο υπάρχειphone exists
not_existsΤο πεδίο δεν υπάρχειreferralCode not_exists
within_next_daysΗμερομηνία εντός των επόμενων N ημερώνtrialEndsDate within_next_days 7

Τελεστές συμβάντων

ΤελεστήςΠεριγραφήΠαράδειγμα
performedΟ χρήστης εκτέλεσε το συμβάνPerformed "Order Completed"
not_performedΟ χρήστης δεν εκτέλεσε το συμβάνNot performed "Onboarding Completed"
performed_count_gteΠλήθος συμβάντων μεγαλύτερο ή ίσο (το N στο value)Performed "Login" >= 10 times
performed_count_lteΠλήθος συμβάντων μικρότερο ή ίσο (το N στο value)Performed "Login" <= 5 times
performed_in_last_daysΕκτελέστηκε τις τελευταίες N ημέρες (το N στο value)Performed "Login" in last 7 days
not_performed_in_last_daysΔεν εκτελέστηκε τις τελευταίες N ημέρες (το N στο value)No "Login" in last 14 days

Παραδείγματα φίλτρων

Φίλτρα γνωρισμάτων

// String matching
{
"type": "attribute",
"field": "email",
"operator": "contains",
"value": "@company.com"
}

// Numeric comparison
{
"type": "attribute",
"field": "lifetimeValue",
"operator": "gte",
"value": 500
}

// Multiple values
{
"type": "attribute",
"field": "plan",
"operator": "in",
"value": ["premium", "enterprise"]
}

// Field exists
{
"type": "attribute",
"field": "phone",
"operator": "exists"
}

// Date within next N days (future dates)
{
"type": "attribute",
"field": "trialEndsDate",
"operator": "within_next_days",
"value": 7
}

Φίλτρα συμβάντων

// Event performed within timeframe
{
"type": "event",
"eventName": "Order Completed",
"operator": "performed",
"withinDays": 30
}

// Event not performed
{
"type": "event",
"eventName": "Onboarding Completed",
"operator": "not_performed"
}

// Event count (N goes in `value`)
{
"type": "event",
"eventName": "Login",
"operator": "performed_count_gte",
"value": 10,
"withinDays": 30
}

Φίλτρα τμημάτων

// User in another segment
{
"type": "segment",
"segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"operator": "in_segment"
}

// User not in another segment
{
"type": "segment",
"segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"operator": "not_in_segment"
}

Συνηθισμένα παραδείγματα τμημάτων

Ευκαιρία μετατροπής δοκιμής

{
"name": "Trial Expiring Soon",
"description": "Users whose trial ends in the next 3 days and haven't purchased",
"filterGroups": [
{
"filters": [
{
"type": "attribute",
"field": "plan",
"operator": "equals",
"value": "trial"
},
{
"type": "attribute",
"field": "trialEndsDate",
"operator": "within_next_days",
"value": 3
},
{
"type": "event",
"eventName": "Order Completed",
"operator": "not_performed"
}
],
"operator": "AND"
}
],
"groupOperator": "AND"
}

Power users

{
"name": "Power Users",
"filterGroups": [
{
"filters": [
{
"type": "event",
"eventName": "Login",
"operator": "performed_count_gte",
"value": 20,
"withinDays": 30
},
{
"type": "event",
"eventName": "Feature Used",
"operator": "performed_count_gte",
"value": 50,
"withinDays": 30
}
],
"operator": "AND"
}
],
"groupOperator": "AND"
}

Πελάτες σε κίνδυνο

{
"name": "At-Risk Premium Users",
"filterGroups": [
{
"filters": [
{
"type": "attribute",
"field": "plan",
"operator": "in",
"value": ["premium", "enterprise"]
},
{
"type": "attribute",
"field": "lifetimeValue",
"operator": "gte",
"value": 500
}
],
"operator": "AND"
},
{
"filters": [
{
"type": "event",
"eventName": "Login",
"operator": "not_performed",
"withinDays": 14
}
],
"operator": "AND"
}
],
"groupOperator": "AND"
}

Δυναμικές ενημερώσεις

Τα τμήματα είναι δυναμικά: η συμμετοχή δεν είναι αποθηκευμένη λίστα - τα φίλτρα του τμήματος αξιολογούνται πάνω στα τρέχοντα δεδομένα προφίλ και συμβάντων κάθε φορά που το τμήμα χρησιμοποιείται (στόχευση καμπανιών, πύλες journeys, έλεγχοι συμμετοχής). Δεν υπάρχει τίποτα προς ανανέωση ή επανυπολογισμό μέσω του API.

Έλεγχος μεγέθους τμήματος

# Get current size (approximate by default; add ?exact=true for a precise count)
curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
-H "Authorization: Bearer jry_live_your_api_key"

Αποκρίσεις σφαλμάτων

Όλα τα σφάλματα χρησιμοποιούν το τυπικό σώμα σφάλματος - δείτε Επισκόπηση API: Απόκριση σφάλματος.

400 Bad Request - Μη έγκυρο φίλτρο

{
"statusCode": 400,
"message": "Bad Request Exception",
"timestamp": "2026-01-15T10:30:00.000Z",
"path": "/segments",
"errors": [
"filterGroups.0.filters.0.operator must be one of the following values: equals, not_equals, contains, ..."
]
}

404 Not Found

{
"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"
}

Όρια ρυθμού

Το Segments API δεν έχει σήμερα σταθερά όρια ρυθμού ανά endpoint - δείτε Επισκόπηση API: Όρια ρυθμού.


Καλές πρακτικές

1. Κρατήστε τα τμήματα εστιασμένα

Σωστό: Συγκεκριμένα, στοχευμένα τμήματα

{
"name": "Premium US Users - Active Last 7 Days",
"filters": [...]
}

Λάθος: Υπερβολικά ευρεία τμήματα

{
"name": "All Users",
"filters": []
}

2. Χρησιμοποιείτε περιγραφικά ονόματα

Σωστό: Αυτονόητα ονόματα

  • «Trial Users - Expiring This Week»
  • «High-Value At-Risk Customers»
  • «New Signups - Not Onboarded»

Λάθος: Ασαφή ονόματα

  • «Segment 1»
  • «Test»
  • «Users ABC»

3. Συνδυάζετε τα φίλτρα λογικά

Χρησιμοποιήστε AND για στένεμα, OR για διεύρυνση:

// AND: Premium users who are active
{
"filters": [
{ "field": "plan", "operator": "equals", "value": "premium" },
{ "eventName": "Login", "operator": "performed", "withinDays": 7 }
],
"operator": "AND"
}

// OR: Users on any paid plan
{
"filters": [
{ "field": "plan", "operator": "equals", "value": "premium" },
{ "field": "plan", "operator": "equals", "value": "enterprise" }
],
"operator": "OR"
}

4. Παρακολουθείτε το μέγεθος του τμήματος

Παρακολουθήστε το μέγεθος του τμήματος στον χρόνο:

// Poll segment size
setInterval(async () => {
const { size, approximate } = await fetch(`/segments/${segmentId}/size`).then(r => r.json());
console.log(`Segment size: ${approximate ? '≈' : ''}${size}`);
}, 60000); // Every minute

Επόμενα βήματα