E-Commerce API

Διαχειριστείτε τον κατάλογο προϊόντων σας, παρακολουθήστε παραγγελίες, εποπτεύστε τη δραστηριότητα καλαθιών και αναλύστε τα τμήματα RFM των πελατών σας.

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

Σύμβαση ονομασίας ID

Το Joryio χρησιμοποιεί μια σαφή σύμβαση ονομασίας για τα αναγνωριστικά:

Τα δικά σας ID (χρησιμοποιήστε τα κατά τη δημιουργία/καταγραφή δεδομένων)

Πεδίο	Περιγραφή	Παράδειγμα
productId	Το δικό σας αναγνωριστικό προϊόντος (SKU, ID προϊόντος από την πλατφόρμα e-commerce σας)	"SKU-12345"
orderId	Το δικό σας αναγνωριστικό παραγγελίας (αριθμός παραγγελίας από την πλατφόρμα σας)	"ORD-2024-001"
userId	Το δικό σας αναγνωριστικό χρήστη	"user-123"

ID του Joryio (επιστρέφονται στις αποκρίσεις του API)

Πεδίο	Περιγραφή	Πότε να το χρησιμοποιήσετε
id	Το εσωτερικό ID του Joryio για προϊόντα/παραγγελίες	Επιστρέφεται στις αποκρίσεις του API· χρησιμοποιήστε το για ενημερώσεις/διαγραφές
joryioUserId	Το εσωτερικό ID χρήστη του Joryio (το 24-hex id που επιστρέφεται στις αποκρίσεις του user API)	Εναλλακτικό του userId όταν θέλετε αναφορά μέσω του ID του Joryio

Ευέλικτη ταυτοποίηση χρήστη

Κατά τη δημιουργία παραγγελιών ή την καταγραφή συμβάντων, μπορείτε να ταυτοποιήσετε χρήστες με οποιοδήποτε από τα δύο:

• userId - Το δικό σας αναγνωριστικό χρήστη (το συνηθέστερο)
• joryioUserId - Το εσωτερικό ID χρήστη του Joryio

// Using your user ID (recommended)
{ "orderId": "ORD-001", "userId": "user-123", ... }

// Using Joryio's internal user ID
{ "orderId": "ORD-001", "joryioUserId": "66a1f2c3d4e5f6a7b8c9d0e1", ... }

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

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

Authorization: Bearer your_jwt_token
Content-Type: application/json
X-Workspace-Id: your_workspace_id

---

Κατάλογος προϊόντων

Δημιουργία προϊόντος

Δημιουργήστε ένα νέο προϊόν στον κατάλογό σας.

POST /catalog/products

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

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
productId	string	Ναι	Το δικό σας μοναδικό αναγνωριστικό προϊόντος (SKU, ID προϊόντος)
name	string	Ναι	Όνομα προϊόντος
price	number	Ναι	Τιμή προϊόντος
description	string	Όχι	Περιγραφή προϊόντος
compareAtPrice	number	Όχι	Αρχική τιμή (για εκπτώσεις)
currency	string	Όχι	Κωδικός νομίσματος (προεπιλογή: USD)
categories	string[]	Όχι	Κατηγορίες προϊόντος
tags	string[]	Όχι	Ετικέτες προϊόντος
brand	string	Όχι	Όνομα επωνυμίας
imageUrl	string	Όχι	URL κύριας εικόνας προϊόντος
url	string	Όχι	URL σελίδας προϊόντος
inStock	boolean	Όχι	Διαθεσιμότητα αποθέματος (προεπιλογή: true)
sku	string	Όχι	Μονάδα διατήρησης αποθέματος (SKU)
variants	object[]	Όχι	Παραλλαγές προϊόντος
customFields	object	Όχι	Προσαρμοσμένα γνωρίσματα

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

curl -X POST https://api-eu1.joryio.com/catalog/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "SKU-12345",
    "name": "Classic Blue T-Shirt",
    "price": 29.99,
    "compareAtPrice": 39.99,
    "currency": "USD",
    "categories": ["Clothing", "T-Shirts"],
    "tags": ["sale", "bestseller"],
    "brand": "Acme Apparel",
    "imageUrl": "https://example.com/images/blue-tshirt.jpg",
    "url": "https://example.com/products/blue-tshirt",
    "inStock": true,
    "sku": "BTS-001-BL",
    "variants": [
      {
        "id": "var-s",
        "name": "Small",
        "sku": "BTS-001-BL-S",
        "price": 29.99,
        "inStock": true,
        "options": { "size": "S", "color": "Blue" }
      },
      {
        "id": "var-m",
        "name": "Medium",
        "sku": "BTS-001-BL-M",
        "price": 29.99,
        "inStock": true,
        "options": { "size": "M", "color": "Blue" }
      }
    ]
  }'

Απόκριση:

{
  "id": "prod_abc123",
  "productId": "SKU-12345",
  "name": "Classic Blue T-Shirt",
  "price": 29.99,
  "createdAt": "2024-01-20T10:00:00.000Z"
}

Μαζικό upsert προϊόντων (σώμα-πίνακας)

Δεν υπάρχει ξεχωριστό endpoint μαζικών λειτουργιών: το POST /catalog/products δέχεται είτε ένα μεμονωμένο αντικείμενο προϊόντος είτε έναν σκέτο πίνακα JSON με αντικείμενα προϊόντων (χωρίς αντικείμενο-περιτύλιγμα). Η μορφή πίνακα δημιουργεί ή ενημερώνει έως 500 προϊόντα σε ένα αίτημα, με upsert βάσει productId.

POST /catalog/products

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

Ένας πίνακας JSON (μέγιστο 500 στοιχεία· κενός πίνακας ή περισσότερα από 500 επιστρέφει 400). Κάθε στοιχείο ακολουθεί την ίδια μορφή με τη μορφή μεμονωμένου αντικειμένου, συμπεριλαμβανομένου του προαιρετικού πεδίου source ανά προϊόν.

Κάθε στοιχείο περνά από πλήρη επικύρωση. Ένα μη έγκυρο στοιχείο αναφέρεται στο failed με τον δείκτη του στον πίνακα - δεν γίνεται ποτέ σιωπηλά αποδεκτό - και τα υπόλοιπα έγκυρα στοιχεία εξακολουθούν να γίνονται upsert.

[
  { "productId": "SKU-001", "name": "Product 1", "price": 19.99 },
  { "productId": "SKU-002", "name": "Product 2", "price": 29.99, "source": "shopify" }
]

Απόκριση:

Σε αντίθεση με τη μορφή αντικειμένου (που επιστρέφει το προϊόν που δημιουργήθηκε), η μορφή πίνακα επιστρέφει μια συγκεντρωτική σύνοψη:

{
  "processed": 2,
  "upserted": 2,
  "failed": []
}

Πεδίο	Περιγραφή
processed	Πλήθος στοιχείων που παραλήφθηκαν στον πίνακα του αιτήματος
upserted	Προϊόντα που πραγματικά δημιουργήθηκαν ή ενημερώθηκαν
failed	Αποτυχίες ανά στοιχείο: index (θέση στον πίνακα του αιτήματος), productId / sku (όταν υπάρχουν στο στοιχείο), reason

Λίστα προϊόντων

Ερώτημα προϊόντων με φιλτράρισμα και σελιδοποίηση.

GET /catalog/products

Παράμετροι query:

Παράμετρος	Τύπος	Περιγραφή
search	string	Αναζήτηση βάσει ονόματος, περιγραφής ή SKU
categories	string[]	Φιλτράρισμα βάσει κατηγοριών
tags	string[]	Φιλτράρισμα βάσει ετικετών
brand	string	Φιλτράρισμα βάσει επωνυμίας
inStock	boolean	Φιλτράρισμα βάσει κατάστασης αποθέματος
minPrice	number	Ελάχιστη τιμή
maxPrice	number	Μέγιστη τιμή
limit	number	Αποτελέσματα ανά σελίδα (προεπιλογή: 50)
offset	number	Μετατόπιση σελιδοποίησης
sortBy	string	Πεδίο ταξινόμησης: name, price, createdAt, updatedAt
sortOrder	string	asc ή desc

Παράδειγμα:

curl "https://api-eu1.joryio.com/catalog/products?categories=T-Shirts&inStock=true&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Λήψη κατηγοριών

Λίστα όλων των κατηγοριών προϊόντων.

GET /catalog/categories

Λήψη επωνυμιών

Λίστα όλων των επωνυμιών προϊόντων.

GET /catalog/brands

Στατιστικά καταλόγου

Σύνολα και υγεία καταλόγου, υπολογισμένα σε όλα τα προϊόντα - ποτέ σε μία σελίδα.

GET /catalog/stats

Απάντηση:

{
  "productCount": 8214,
  "categoryCount": 37,
  "brandCount": 12,
  "outOfStockCount": 341,
  "lowStockCount": 96,
  "unclassifiedCount": 18,
  "lowStockThreshold": 10
}

Πεδίο	Περιγραφή
outOfStockCount	Προϊόντα με quantity 0, ή inStock: false όταν δεν παρακολουθείται ποσότητα
lowStockCount	Προϊόντα με quantity από 1 έως lowStockThreshold
unclassifiedCount	Προϊόντα χωρίς κατηγορία ή χωρίς μάρκα
lowStockThreshold	Το όριο μονάδων στο οποίο υπολογίστηκε το lowStockCount

---

Παραγγελίες

Δημιουργία παραγγελίας

Καταγράψτε μια νέα παραγγελία.

POST /orders

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

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
orderId	string	Ναι	Το δικό σας ID παραγγελίας (αριθμός παραγγελίας από την πλατφόρμα σας)
userId	string	Ένα από τα δύο	Το δικό σας ID χρήστη-πελάτη
joryioUserId	string	Ένα από τα δύο	Το εσωτερικό ID χρήστη του Joryio (εναλλακτικό του userId)
total	number	Ναι	Σύνολο παραγγελίας
items	object[]	Ναι	Γραμμές παραγγελίας
status	string	Όχι	Κατάσταση παραγγελίας (προεπιλογή: pending)
currency	string	Όχι	Κωδικός νομίσματος
subtotal	number	Όχι	Μερικό σύνολο πριν τις εκπτώσεις
discount	number	Όχι	Ποσό έκπτωσης
shipping	number	Όχι	Κόστος αποστολής
tax	number	Όχι	Ποσό φόρου
totalRefunded	number	Όχι	Ποσό που επιστράφηκε μέχρι τώρα, στο νόμισμα της παραγγελίας (προεπιλογή 0). Για μερική επιστροφή στείλτε το μερικό ποσό με status: partiallyRefunded· για πλήρη επιστροφή ορίστε το στο total με status: refunded. Οι επιστροφές αφαιρούνται από τα αποδιδόμενα έσοδα.
couponCode	string	Όχι	Εφαρμοσμένο κουπόνι
shippingAddress	object	Όχι	Διεύθυνση αποστολής
campaignId	string	Όχι	Καμπάνια απόδοσης (attribution)
canvasId	string	Όχι	Canvas απόδοσης (attribution)
source	string	Όχι	Πηγή παραγγελίας (email, sms, direct)
utmSource	string	Όχι	UTM source
utmMedium	string	Όχι	UTM medium
utmCampaign	string	Όχι	UTM campaign

Ταυτοποίηση χρήστη

Πρέπει να παρέχεται είτε το userId είτε το joryioUserId. Χρησιμοποιήστε το userId με τα δικά σας αναγνωριστικά χρηστών (το συνηθέστερο). Χρησιμοποιήστε το joryioUserId όταν έχετε το εσωτερικό ID χρήστη του Joryio (το 24-hex id που επιστρέφεται στις αποκρίσεις του user API).

Δομή γραμμής παραγγελίας:

{
  "productId": "prod_abc123",
  "name": "Blue T-Shirt",
  "sku": "BTS-001",
  "quantity": 2,
  "price": 29.99,
  "total": 59.98,
  "imageUrl": "https://example.com/image.jpg"
}

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

curl -X POST https://api-eu1.joryio.com/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-2024-001",
    "userId": "user-123",
    "total": 89.97,
    "subtotal": 99.97,
    "discount": 10.00,
    "shipping": 5.99,
    "tax": 4.99,
    "currency": "USD",
    "couponCode": "SAVE10",
    "items": [
      {
        "productId": "prod_abc123",
        "name": "Blue T-Shirt",
        "quantity": 2,
        "price": 29.99,
        "total": 59.98
      },
      {
        "productId": "prod_def456",
        "name": "Black Jeans",
        "quantity": 1,
        "price": 49.99,
        "total": 49.99
      }
    ],
    "source": "email",
    "campaignId": "camp_xyz789"
  }'

Ολοκλήρωση παραγγελίας (fulfill)

Επισημάνετε μια παραγγελία ως απεσταλμένη.

POST /orders/:id/fulfill

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

{
  "trackingNumber": "1Z999AA10123456784",
  "carrier": "UPS"
}

Ακύρωση παραγγελίας

Ακυρώστε μια παραγγελία.

POST /orders/:id/cancel

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

{
  "reason": "Customer requested cancellation"
}

Επιστροφή χρημάτων παραγγελίας

Επεξεργαστείτε μια επιστροφή χρημάτων.

POST /orders/:id/refund

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

{
  "refundAmount": 29.99,
  "reason": "Product defective",
  "partial": true
}

Στατιστικά παραγγελιών

Λήψη στατιστικών παραγγελιών για ένα εύρος ημερομηνιών.

GET /orders/stats?startDate=2024-01-01&endDate=2024-01-31

Απόκριση:

{
  "totalOrders": 156,
  "totalRevenue": 12450.50,
  "averageOrderValue": 79.81,
  "ordersByStatus": {
    "pending": 5,
    "processing": 12,
    "shipped": 45,
    "delivered": 90,
    "cancelled": 4
  }
}

---

Παρακολούθηση καλαθιών

Ενημέρωση καλαθιού

Καταγράψτε ή ενημερώστε το καλάθι ενός χρήστη.

PUT /carts

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

{
  "userId": "user_123",
  "items": [
    {
      "productId": "prod_abc123",
      "name": "Blue T-Shirt",
      "price": 29.99,
      "quantity": 2,
      "total": 59.98,
      "imageUrl": "https://example.com/image.jpg"
    }
  ],
  "value": 59.98,
  "currency": "USD",
  "checkoutUrl": "https://store.example.com/checkout?cart=abc123"
}

Προσθήκη στο καλάθι

Προσθέστε ένα προϊόν στο καλάθι ενός χρήστη.

POST /carts/add

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

{
  "userId": "user_123",
  "item": {
    "productId": "prod_abc123",
    "name": "Blue T-Shirt",
    "price": 29.99,
    "quantity": 1,
    "total": 29.99
  }
}

Λήψη εγκαταλελειμμένων καλαθιών

Λίστα εγκαταλελειμμένων καλαθιών για καμπάνιες ανάκτησης.

GET /carts/abandoned

Παράμετροι query:

Παράμετρος	Τύπος	Περιγραφή
minValue	number	Ελάχιστη αξία καλαθιού
abandonedMinutesAgo	number	Μέγιστα λεπτά από την εγκατάλειψη
limit	number	Αποτελέσματα ανά σελίδα
offset	number	Μετατόπιση σελιδοποίησης

Απόκριση:

{
  "data": [
    {
      "id": "cart_123",
      "userId": "user_456",
      "items": [...],
      "value": 149.99,
      "abandonedAt": "2024-01-20T15:30:00.000Z",
      "checkoutUrl": "https://store.example.com/checkout?cart=abc"
    }
  ],
  "total": 42,
  "hasMore": true
}

Στατιστικά καλαθιών

Λήψη στατιστικών καλαθιών και εγκατάλειψης.

GET /carts/stats

Απόκριση:

{
  "totalCarts": 1250,
  "abandonedCarts": 312,
  "recoveredCarts": 87,
  "totalAbandonedValue": 45670.50,
  "recoveryRate": 27.88
}

---

Ανάλυση RFM

Η ανάλυση RFM (Recency, Frequency, Monetary - πρόσφατη επαφή, συχνότητα, χρηματική αξία) τμηματοποιεί τους πελάτες βάσει της αγοραστικής τους συμπεριφοράς.

Λήψη δεδομένων RFM χρήστη

Λήψη βαθμολογιών RFM και τμήματος για έναν συγκεκριμένο χρήστη.

GET /rfm/user/:userId

Απόκριση:

{
  "totalOrders": 12,
  "totalSpent": 849.50,
  "averageOrderValue": 70.79,
  "firstOrderDate": "2023-06-15T10:00:00.000Z",
  "lastOrderDate": "2024-01-18T14:30:00.000Z",
  "daysSinceLastOrder": 2,
  "hasActiveCart": false,
  "rfmRecency": 5,
  "rfmFrequency": 4,
  "rfmMonetary": 4,
  "rfmScore": "544",
  "rfmSegment": "champions"
}

Λήψη κατανομής RFM

Λήψη της κατανομής πελατών στα τμήματα RFM.

GET /rfm/distribution

Απόκριση:

{
  "champions": { "count": 150, "totalValue": 125000 },
  "loyal": { "count": 320, "totalValue": 89000 },
  "potential_loyalists": { "count": 180, "totalValue": 32000 },
  "new_customers": { "count": 450, "totalValue": 28000 },
  "at_risk": { "count": 95, "totalValue": 42000 },
  "lost": { "count": 280, "totalValue": 15000 }
}

Τμήματα RFM

Τμήμα	Περιγραφή	Τυπικές βαθμολογίες RFM
Champions	Οι καλύτεροι πελάτες: αγοράζουν συχνά, ξοδεύουν τα περισσότερα	555, 554, 545
Loyal	Σταθεροί πελάτες	444, 443, 434
Potential Loyalists	Πρόσφατοι με μέση συχνότητα	433, 343, 333
New Customers	Μόλις έκαναν την πρώτη τους αγορά	511, 512, 411
Promising	Πρόσφατοι αλλά με χαμηλή συχνότητα	422, 322, 312
Needs Attention	Μέσοι, με φθίνουσα αλληλεπίδραση	332, 322, 233
About to Sleep	Κάτω από τον μέσο όρο, σε κίνδυνο	211, 212, 221
At Risk	Ήταν πιστοί, δεν έχουν αγοράσει πρόσφατα	144, 143, 244
Can't Lose	Ήταν οι καλύτεροι πελάτες, τώρα ανενεργοί	155, 154, 255
Hibernating	Χαμηλή αλληλεπίδραση, ανενεργοί για καιρό	122, 121, 112
Lost	Χαμηλότερες βαθμολογίες, πιθανότατα χαμένοι	111

---

Webhooks

Τα συμβάντα e-commerce εκπέμπουν webhooks που μπορούν να ενεργοποιήσουν ροές canvas:

Συμβάν	Περιγραφή
ecommerce.order.created	Νέα παραγγελία καταχωρήθηκε
ecommerce.order.fulfilled	Η παραγγελία απεστάλη
ecommerce.order.cancelled	Η παραγγελία ακυρώθηκε
ecommerce.order.refunded	Έγινε επιστροφή χρημάτων παραγγελίας
ecommerce.order.status_changed	Η κατάσταση της παραγγελίας άλλαξε
ecommerce.cart.abandoned	Το καλάθι επισημάνθηκε ως εγκαταλελειμμένο
ecommerce.cart.recovered	Το εγκαταλελειμμένο καλάθι ανακτήθηκε
ecommerce.cart.updated	Το περιεχόμενο του καλαθιού άλλαξε

---

Αναζήτηση με τα δικά σας ID

Λήψη προϊόντος με το δικό σας ID προϊόντος

Ανακτήστε ένα προϊόν χρησιμοποιώντας το δικό σας αναγνωριστικό προϊόντος.

GET /catalog/products/by-product-id/:productId

Παράδειγμα:

curl "https://api-eu1.joryio.com/catalog/products/by-product-id/SKU-12345" \
  -H "Authorization: Bearer $TOKEN"

Λήψη παραγγελίας με το δικό σας ID παραγγελίας

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

GET /orders/by-order-id/:orderId

Παράδειγμα:

curl "https://api-eu1.joryio.com/orders/by-order-id/ORD-2024-001" \
  -H "Authorization: Bearer $TOKEN"

---

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

{
  "statusCode": 404,
  "message": "Product SKU-12345 not found",
  "error": "Not Found"
}

Κωδικός κατάστασης	Περιγραφή
400	Μη έγκυρο σώμα αιτήματος
401	Απαιτείται έλεγχος ταυτότητας
403	Ανεπαρκή δικαιώματα
404	Ο πόρος δεν βρέθηκε
409	Σύγκρουση (διπλότυπο εξωτερικό ID)
500	Εσωτερικό σφάλμα διακομιστή