Επισκόπηση Canvas API
Διαχειριστείτε journeys του Canvas - αυτοματισμούς πολλαπλών βημάτων που δημιουργούνται στον οπτικό δημιουργό journeys - μέσω του REST API.
Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com/api - δείτε Επισκόπηση 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:enter | Είσοδος χρήστη (trigger API) - και τίποτα άλλο. Περιλαμβάνεται στο canvas:activate |
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/api/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 Το timeOfDay είναι HH:MM σε 24ωρη μορφή (09:00, 17:30)· οποιαδήποτε άλλη τιμή απορρίπτεται με 400. |
targeting | object | Όχι | Κοινό για scheduled/immediate journeys: userIds, filterGroups, excludeFilterGroups, filterOperator, subscriptionPreference |
exitCriteria | object | Όχι | Ίδια μορφή φίλτρων με το targeting· οι ενεργοί χρήστες που ταιριάζουν εξέρχονται |
tags | string[] | Όχι | Ετικέτες |
Δομή κόμβου
Κάθε στοιχείο στο nodes έχει id, type, config (ειδικό ανά τύπο) και προαιρετικό position (x/y για τον επεξεργαστή). Έγκυρες τιμές type:
trigger, message, in_app_message, delay, condition, behavior_split,
context, update_user, update_wallet, connector, experiment,
ai_decision, ai_agent
Υπάρχει ένας κόμβος message· το κανάλι είναι το config.channel (email, sms, push, whatsapp, viber, in_app, webhook). Οι παλιοί τύποι κόμβων ανά κανάλι - email, sms, push, whatsapp, whatsapp_message, wallet, webhook και το ψευδώνυμο in_app - αφαιρέθηκαν και πλέον απορρίπτονται στη δημιουργία και στην ενημέρωση.
Κάθε στοιχείο στο edges έχει id, source, target και προαιρετικά sourceHandle / targetHandle / label - το sourceHandle επιλέγει τη θύρα εξόδου σε κόμβους πολλαπλών εξόδων (ομάδες διακλάδωσης, did / timed_out του behavior-split).
Έναυσμα εισόδου
Το entryTrigger έχει ένα type και ένα config ειδικό ανά τύπο. Έγκυροι τύποι: event, api, entity_change, whatsapp_inbound, sms_inbound, viber_inbound, attribute_change, subscription_status, schedule.
Η Είσοδος σε τμήμα δεν είναι έναυσμα. Για εισόδους που προκαλούνται από κάτι που έκανε το άτομο, χρησιμοποιήστε έναυσμα Συμβάντος με φίλτρο· για εισόδους που προκαλούνται από το πέρασμα του χρόνου, χρησιμοποιήστε μια επαναλαμβανόμενη διαδρομή πάνω στο τμήμα.
Παραλλαγές ολόκληρου του journey
Κάθε στοιχείο στο variants: id, name, percentage (0-100· όλες οι παραλλαγές πρέπει να αθροίζουν σε 100), isControlGroup (μια παραλλαγή ελέγχου είναι μετρούμενο παρακρατημένο κοινό χωρίς ροή) και triggerNodeId (ο κόμβος εναύσματος στον οποίο ριζώνει αυτή η παραλλαγή). Δείτε τα αναλυτικά στοιχεία journeys για το πώς αναφέρονται τα αποτελέσματα παραλλαγών. Το πεδίο ονομαζόταν παλαιότερα isControl· η γραφή αυτή εξακολουθεί να γίνεται δεκτή κατά την εγγραφή και μετατρέπεται σε isControlGroup.
Παράδειγμα αιτήματος
curl -X POST https://api-eu1.joryio.com/api/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/api/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/api/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). Μόνο για journey που είναι ήδη ζωντανό (status: active)· διαφορετικά 409 με code: "journey_not_live" - η πρώτη ενεργοποίηση γίνεται με POST /journeys/:canvasId/activate. |
POST | /journeys/:canvasId/rerun | canvas:activate | Επανεκτέλεση της τρέχουσας δημοσιευμένης έκδοσης χωρίς δημιουργία νέας |
curl -X POST https://api-eu1.joryio.com/api/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
Δικαίωμα: canvas:enter (περιλαμβάνεται στο canvas:activate), ώστε μια ενσωμάτωση όπως το Zapier να μπορεί να προσθέτει άτομα σε ένα journey χωρίς να μπορεί να το ξεκινήσει, να το παύσει ή να το επεξεργαστεί.
Σώμα (προαιρετικό): context - ένα αντικείμενο JSON που γίνεται διαθέσιμο στην εκτέλεση (αναγνώσιμο σε μηνύματα και συνθήκες ως μεταβλητές context του journey).
curl -X POST https://api-eu1.joryio.com/api/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" } }'
Λίστα των journeys στα οποία μπορεί να μπει ένα άτομο
GET /journeys/enterable?q=
Τα ενεργά (active) journeys, ως { "data": [{ "id", "name", "activatedAt" }] }, ταξινομημένα κατά όνομα, έως 100· το q φιλτράρει με μέρος του ονόματος. Δικαίωμα: canvas:enter (ή canvas:read) - μια ενσωμάτωση που μπορεί να προσθέτει άτομα σε journeys επιλέγει ένα χωρίς να διαβάζει τα ίδια τα journeys.
Εκτελέσεις και αναλυτικά στοιχεία
| Μέθοδος | Διαδρομή | Περιγραφή |
|---|---|---|
GET | /journeys/:canvasId/executions | Λίστα εκτελέσεων (status, limit μέγιστο 100, offset) |
GET | /journeys/:canvasId/executions/:executionId | Λήψη μίας εκτέλεσης. Κάθε βήμα webhook στο history φέρει webhook (κατάσταση, επιτυχία, διάρκεια, προσπάθειες, σφάλμα, αποθηκευμένα πεδία)· μια αποτυχημένη κλήση (εκτός 2xx) προσθέτει webhook.response ({ status, contentType, body, truncated }) - με αποκρυμμένα μυστικά, τα πρώτα 2 KB του σώματος, διατηρείται 30 ημέρες, επιστρέφεται μόνο σε καλούντα με pii:view (κλειδί API μόνο με αυτό το δικαίωμα· οι άλλοι λαμβάνουν webhook.responseHidden: true). Το σώμα μιας επιτυχημένης απάντησης δεν αποθηκεύεται ποτέ |
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/recovered-carts | Τα εγκαταλελειμμένα καλάθια που ανέκτησε η διαδρομή - η λίστα πίσω από το revenue.recoveredCarts στο /stats, από το ίδιο ερώτημα, οπότε το total ισούται με αυτή τη μέτρηση για τα ίδια startDate/endDate (καλάθια που ανακτήθηκαν στο εύρος· ένα τέλος μόνο με ημερομηνία περιλαμβάνει όλη την ημέρα, ζώνη ώρας χώρου εργασίας). limit 1-100 (προεπιλογή 25), offset· οι νεότερες πρώτα. Γραμμές: orderNumber (του καταστήματος), placedAt, recoveredAt, match (recovery_link, order = ίδιο καλάθι, reported), cartValue/cartCurrency, creditedRevenue/creditedCurrency (καθαρά από επιστροφές), contact (ο κάτοχος του καλαθιού) και buyer (μόνο όταν η παραγγελία καταχωρίστηκε σε άλλο άτομο)· τα ονόματα επαφών κρύβονται χωρίς pii:view. Επιστρέφει { data, total, limit, offset, summary } |
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) σε μια έκδοση. Μόνο για ζωντανά journeys· διαφορετικά 409 journey_not_live. |
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 μία φορά και επιστροφή της απόκρισης μαζί με το αίτημα που στάλθηκε (με απόκρυψη διαπιστευτηρίων). Το user.userId αποδίδει μια πραγματική επαφή του χώρου εργασίας ακριβώς όπως μια πραγματική αποστολή· αλλιώς χρησιμοποιούνται δειγματικές τιμές (με όριο ρυθμού) |
POST | /journeys/preview-context-value | Απόδοση μιας έκφρασης Liquid σε δείγμα πεδίου τιμών |
POST | /journeys/preview-user-updates | Dry-run των γραμμών ενός κόμβου Update User σε δείγμα χρήστη |
POST | /journeys/preview-user-update-json | Dry-run του Προσαρμοσμένου JSON ενός κόμβου Update User: εισέρχεται { json, sample }, επιστρέφει { errors, preview: { errors, result } }. Τα errors εμποδίζουν αποθήκευση ή ενεργοποίηση· το preview είναι το JSON αποδοσμένο στο δείγμα. Δεν γράφει τίποτα |
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 | Αποδοσμένο μήνυμα για μία εκτέλεση + κόμβο |
Έλεγχος αποστολής
Ο ίδιος έλεγχος πριν την αποστολή που έχουν οι καμπάνιες (δείτε τον οδηγό Ελέγχου αποστολής), εκτελείται σε κάθε κόμβο μηνύματος: σύνδεσμος διαγραφής, πεδία συγχώνευσης, επαλήθευση αποστολέα, άχρηστοι σύνδεσμοι, μήκος θέματος, έλλειψη απλού κειμένου, ώρες ησυχίας, συν node_unreachable για κόμβους στους οποίους δεν φτάνει κανένα έναυσμα, cart_variable_no_cart_trigger για μήνυμα που διαβάζει cart σε ταξίδι που δεν ξεκινά με συμβάν καλαθιού, και channel_not_set_up για κανάλι που χρησιμοποιεί το ταξίδι χωρίς πάροχο ή αποστολέα (params.channel· εμπόδιο, ή σύσταση με params.sandbox: 1 σε χώρο εργασίας επίδειξης, όπου οι αποστολές προσομοιώνονται για όλους). Η ενεργοποίηση και η δημοσίευση τον τρέχουν επίσης.
GET /journeys/{canvasId}/launch-review
Εμβέλεια: canvas:read. Η απόκριση έχει τη μορφή που τεκμηριώνεται στο API Καμπανιών· ένα εύρημα κόμβου φέρει scope.kind = "node", scope.id = το id του κόμβου και fix.nodeId.
Όταν ο χώρος εργασίας απαιτεί καθαρή λίστα (settings.launchReview.requireClean, προεπιλογή true) και υπάρχουν εμπόδια, τα POST /journeys/{canvasId}/activate και POST /journeys/{canvasId}/publish απαντούν 409 με code: "launch_review_blocked" και τα εμπόδια στο σώμα.
Αποκρίσεις σφαλμάτων
Όλα τα σφάλματα μοιράζονται την τυπική μορφή - δείτε Απόκριση σφάλματος στην Επισκόπηση 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"
}