Επισκόπηση Canvas API
Διαχειριστείτε journeys του Canvas - αυτοματισμούς πολλαπλών βημάτων που δημιουργούνται στον οπτικό δημιουργό journeys - μέσω του REST API.
Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com - δείτε Επισκόπηση API.
Τα endpoints του Canvas βρίσκονται κάτω από τη διαδρομή /journeys - το όνομα πόρου του API για ένα canvas είναι journey. Το canvasId και το id του journey αναφέρονται στο ίδιο αναγνωριστικό.
Έλεγχος ταυτότητας
Όλα τα αιτήματα απαιτούν έλεγχο ταυτότητας με κλειδί API:
Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json
Απαιτούμενα scopes ανά ομάδα endpoints:
| Scope | Endpoints |
|---|---|
canvas:read | Λίστα, λήψη, εκτελέσεις, στατιστικά, αναλυτικά ανά κόμβο, εκδόσεις |
canvas:write | Δημιουργία, ενημέρωση, αντιγραφή, αρχειοθέτηση, ετικέτες, παραλλαγές, πειράματα |
canvas:activate | Ενεργοποίηση, παύση, συνέχιση, δημοσίευση, επανεκτέλεση, είσοδος χρήστη, rollback |
canvas:delete | Διαγραφή, μαζική διαγραφή |
Λίστα journeys
GET /journeys
Παράμετροι query
| Παράμετρος | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
status | string | - | Φιλτράρισμα βάσει κατάστασης |
tags | string | - | Φιλτράρισμα βάσει ετικετών (χωρισμένες με κόμμα) |
q | string | - | Αναζήτηση ελεύθερου κειμένου |
createdBy / editedBy | string | - | Φιλτράρισμα βάσει δημιουργού / τελευταίου συντάκτη (ids χρηστών χωρισμένα με κόμμα) |
page | number | 1 | Αριθμός σελίδας |
limit | number | - | Αποτελέσματα ανά σελίδα (μέγιστο 100) |
Παράδειγμα αιτήματος
curl -X GET "https://api-eu1.joryio.com/journeys?status=active&limit=20" \
-H "Authorization: Bearer jry_live_your_api_key"
Απόκριση
{
"data": [
{ "id": "3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f", "name": "Welcome journey", "status": "active" }
],
"pagination": {
"total": 8,
"page": 1,
"limit": 20,
"offset": 0,
"totalPages": 1,
"hasMore": false
}
}
Δημιουργία journey
POST /journeys
Σώμα αιτήματος
| Πεδίο | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
name | string | Ναι | Όνομα journey (μέγιστο 255 χαρακτήρες) |
description | string | Όχι | Περιγραφή (μέγιστο 1000 χαρακτήρες) |
nodes | array | Όχι | Κόμβοι γράφου (μέγιστο 500). Ένα προσχέδιο που δημιουργήθηκε από τον οδηγό μπορεί να ξεκινήσει κενό |
edges | array | Όχι | Ακμές γράφου (μέγιστο 1000) |
entryTrigger | object | Όχι | Πώς εισέρχονται οι χρήστες - δείτε παρακάτω |
variants | array | Όχι | Παραλλαγές A/B/n ολόκληρου του journey - δείτε παρακάτω |
settings | object | Όχι | timezone, quietTime, conversionTracking, reEntryPolicy, personalizedVariants + ρύθμιση |
sendType | string | Όχι | immediate, scheduled, recurring ή trigger |
scheduledAt | string | Όχι | Ημερομηνία ISO 8601 για sendType: "scheduled" |
recurringSchedule | object | Όχι | frequency (daily/weekly/monthly/custom), cron, dayOfWeek, dayOfMonth, timeOfDay, timezone, endDate, maxOccurrences |
targeting | object | Όχι | Κοινό για scheduled/immediate journeys: userIds, filterGroups, excludeFilterGroups, filterOperator, subscriptionPreference |
exitCriteria | object | Όχι | Ίδια μορφή φίλτρων με το targeting· οι ενεργοί χρήστες που ταιριάζουν εξέρχονται |
tags | string[] | Όχι | Ετικέτες |
Δομή κόμβου
Κάθε στοιχείο στο nodes έχει id, type, config (ειδικό ανά τύπο) και προαιρετικό position (x/y για τον επεξεργαστή). Έγκυρες τιμές type:
trigger, delay, condition, behavior_split, context, message,
email, sms, push, in_app, in_app_message, whatsapp, whatsapp_message,
webhook, update_user, connector, experiment, ai_decision,
wallet, update_wallet
Κάθε στοιχείο στο edges έχει id, source, target και προαιρετικά sourceHandle / targetHandle / label - το sourceHandle επιλέγει τη θύρα εξόδου σε κόμβους πολλαπλών εξόδων (ομάδες διακλάδωσης, did / timed_out του behavior-split).
Έναυσμα εισόδου
Το entryTrigger έχει ένα type και ένα config ειδικό ανά τύπο. Έγκυροι τύποι: event, segment, api, entity_change, whatsapp_inbound, sms_inbound, viber_inbound, attribute_change, subscription_status, schedule.
Παραλλαγές ολόκληρου του journey
Κάθε στοιχείο στο variants: id, name, percentage (0-100· όλες οι παραλλαγές πρέπει να αθροίζουν σε 100), isControl (μια παραλλαγή ελέγχου είναι μετρούμενο παρακρατημένο κοινό χωρίς ροή) και triggerNodeId (ο κόμβος εναύσματος στον οποίο ριζώνει αυτή η παραλλαγή). Δείτε τα αναλυτικά στοιχεία journeys για το πώς αναφέρονται τα αποτελέσματα παραλλαγών.
Παράδειγμα αιτήματος
curl -X POST https://api-eu1.joryio.com/journeys \
-H "Authorization: Bearer jry_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Welcome journey",
"sendType": "trigger",
"entryTrigger": {
"type": "event",
"config": { "eventName": "signed_up" }
},
"nodes": [
{ "id": "n1", "type": "trigger", "config": { "type": "event", "eventName": "signed_up" } },
{ "id": "n2", "type": "delay", "config": { "delayType": "duration", "value": 1, "unit": "days" } },
{ "id": "n3", "type": "email", "config": { "subject": "Welcome!", "html": "<p>Hi {{ user.firstName }}</p>" } }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2" },
{ "id": "e2", "source": "n2", "target": "n3" }
]
}'
Επιστρέφει το αντικείμενο του journey που δημιουργήθηκε (κατάσταση draft).
Λήψη journey
GET /journeys/:canvasId
curl -X GET https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f \
-H "Authorization: Bearer jry_live_your_api_key"
Επιστρέφει το πλήρες journey, συμπεριλαμβανομένων των nodes, edges, entryTrigger, variants και settings.
Ενημέρωση journey
PUT /journeys/:canvasId
Το σώμα δέχεται τα ίδια πεδία με τη Δημιουργία journey - όλα προαιρετικά· ενημερώνονται μόνο τα πεδία που παρέχονται.
curl -X PUT https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f \
-H "Authorization: Bearer jry_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "name": "Welcome journey v2" }'
Διαγραφή journey
DELETE /journeys/:canvasId
Επιστρέφει 204 No Content. Journeys με ιστορικό εκτελέσεων πρέπει αντ' αυτού να αρχειοθετούνται (POST /journeys/:canvasId/archive), κάτι που σταματά τις εισόδους και την αποστολή διατηρώντας τα αναλυτικά στοιχεία.
Endpoints κατάστασης
| Μέθοδος | Διαδρομή | Scope | Περιγραφή |
|---|---|---|---|
POST | /journeys/:canvasId/activate | canvas:activate | Ενεργοποίηση - οι χρήστες μπορούν να αρχίσουν να εισέρχονται |
POST | /journeys/:canvasId/pause | canvas:activate | Παύση - σταματά νέες εισόδους και την πρόοδο |
POST | /journeys/:canvasId/resume | canvas:activate | Συνέχιση ενός journey σε παύση |
POST | /journeys/:canvasId/archive | canvas:write | Αρχειοθέτηση (σταματά εισόδους/αποστολή, διατηρεί το ιστορικό) |
POST | /journeys/:canvasId/unarchive | canvas:write | Επαναφορά σε κατάσταση μη εκτέλεσης· ενεργοποιήστε ρητά για να συνεχίσει |
POST | /journeys/:canvasId/publish | canvas:activate | Δημοσίευση του τρέχοντος προσχεδίου ως νέας έκδοσης. Σώμα: προαιρετικά changeSummary, userTransition (keep_on_version / force_exit / migrate_to_new) |
POST | /journeys/:canvasId/rerun | canvas:activate | Επανεκτέλεση της τρέχουσας δημοσιευμένης έκδοσης χωρίς δημιουργία νέας |
curl -X POST https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f/activate \
-H "Authorization: Bearer jry_live_your_api_key"
Είσοδος χρήστη (έναυσμα API)
Εγγράψτε έναν συγκεκριμένο χρήστη σε ένα journey - η διαδρομή εισόδου για entryTrigger.type: "api".
POST /journeys/:canvasId/enter/:userId
Σώμα (προαιρετικό): context - ένα αντικείμενο JSON που γίνεται διαθέσιμο στην εκτέλεση (αναγνώσιμο σε μηνύματα και συνθήκες ως μεταβλητές context του journey).
curl -X POST https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f/enter/user_123 \
-H "Authorization: Bearer jry_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "context": { "source": "crm-sync", "priority": "high" } }'
Εκτελέσεις και αναλυτικά στοιχεία
| Μέθοδος | Διαδρομή | Περιγραφή |
|---|---|---|
GET | /journeys/:canvasId/executions | Λίστα εκτελέσεων (status, limit μέγιστο 100, offset) |
GET | /journeys/:canvasId/executions/:executionId | Λήψη μίας εκτέλεσης |
GET | /journeys/:canvasId/executions/:executionId/context | Μεταβλητές context της εκτέλεσης με συναγόμενους τύπους |
GET | /journeys/:canvasId/stats | Στατιστικά σε επίπεδο journey (startDate, endDate) |
GET | /journeys/:canvasId/node-analytics | Αναλυτικά στοιχεία ανά κόμβο (startDate, endDate) |
GET | /journeys/:canvasId/variant-stats | Απόδοση παραλλαγών ολόκληρου του journey (A/B/n + έλεγχος) |
GET | /journeys/:canvasId/experiments/:nodeId/stats | Στατιστικά κόμβου πειράματος με έλεγχο σημαντικότητας |
POST | /journeys/:canvasId/experiments/:nodeId/declare-winner | Ανακήρυξη νικητή (σώμα: pathId) |
POST | /journeys/:canvasId/experiments/:nodeId/reset | Επαναφορά πειράματος σε συλλογή δεδομένων |
GET | /journeys/:canvasId/personalization-status | Κατάσταση φάσης εξατομικευμένων παραλλαγών |
Πρόσθετα endpoints
| Μέθοδος | Διαδρομή | Περιγραφή |
|---|---|---|
PUT | /journeys/:canvasId/variants | Ορισμός παραλλαγών ολόκληρου του journey (σώμα: πίνακας variants) |
GET | /journeys/:canvasId/versions | Λίστα εκδόσεων |
GET | /journeys/:canvasId/versions/compare?v1=&v2= | Σύγκριση (diff) δύο εκδόσεων |
GET | /journeys/:canvasId/versions/compare-draft | Σύγκριση του τρέχοντος προσχεδίου με την τελευταία δημοσιευμένη έκδοση |
GET | /journeys/:canvasId/versions/migration-preview | Προεπισκόπηση συμβατότητας εκτελέσεων πριν από δημοσίευση με μετάβαση |
GET | /journeys/:canvasId/versions/:versionId | Λήψη έκδοσης |
POST | /journeys/:canvasId/versions/:versionId/rollback | Επαναφορά (rollback) σε μια έκδοση |
GET | /journeys/:canvasId/versions/:versionId/stats | Στατιστικά συγκεκριμένης έκδοσης |
GET | /journeys/:canvasId/versions/:versionId/executions | Εκτελέσεις σε συγκεκριμένη έκδοση |
GET | /journeys/:canvasId/version-execution-counts | Πλήθος εκτελέσεων ανά έκδοση |
POST | /journeys/:canvasId/versions/:versionId/migrate | Εξαναγκασμένη μετάβαση συμβατών εκτελέσεων σε μια έκδοση |
GET | /journeys/:canvasId/history | Ιστορικό ελέγχου (audit log) (limit, μέγιστο 200) |
POST | /journeys/bulk-delete / bulk-duplicate / bulk-archive / bulk-unarchive | Μαζικές ενέργειες· σώμα { "ids": [...] }, επιστρέφει { succeeded, failed } |
POST | /journeys/bulk-tag | Μαζική προσθήκη ετικετών· σώμα { "ids": [...], "tags": [...] } |
POST | /journeys/webhook/test | Εκτέλεση μιας ρύθμισης κόμβου webhook μία φορά σε δείγμα context (με όριο ρυθμού) |
POST | /journeys/preview-context-value | Απόδοση μιας έκφρασης Liquid σε δείγμα πεδίου τιμών |
POST | /journeys/preview-user-updates | Dry-run των γραμμών ενός κόμβου Update User σε δείγμα χρήστη |
POST | /journeys/:canvasId/nodes/:nodeId/send-test-email / send-test-sms / send-test-whatsapp / send-test-push | Δοκιμαστική αποστολή ενός κόμβου μηνύματος |
POST | /journeys/:canvasId/cleanup-stuck-executions | Εκκαθάριση κολλημένων εκτελέσεων |
GET | /journeys/:canvasId/executions/:executionId/rendered-message/:nodeId | Αποδοσμένο μήνυμα για μία εκτέλεση + κόμβο |
Αποκρίσεις σφαλμάτων
Όλα τα σφάλματα μοιράζονται την τυπική μορφή - δείτε Απόκριση σφάλματος στην Επισκόπηση API για τη μορφή, τους κωδικούς κατάστασης και τη συμπεριφορά ορίων ρυθμού.
{
"statusCode": 404,
"message": "Canvas with ID 8f14e45f-ceea-467f-a11d-2f4b6a1c9e3b not found",
"timestamp": "2026-07-12T09:00:00.000Z",
"path": "/journeys/8f14e45f-ceea-467f-a11d-2f4b6a1c9e3b"
}