Τεκμηρίωση του Fabrixa Integration API

Για πρόσβαση στο Integration API, ελέγξτε την ταυτότητα των αιτημάτων σας χρησιμοποιώντας τόσο ένα Application Access Token όσο και ένα Application Key:

Κεφαλίδα Authorization

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Κεφαλίδα Application Key

X-Application-Key: APPLICATION_KEY

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

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/ping' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Αντικαταστήστε το APPLICATION_ACCESS_TOKEN με το πραγματικό σας access token και το APPLICATION_KEY με το πραγματικό σας application key.

Τα endpoints του Integration API είναι οργανωμένα ανά τύπο πόρου και ακολουθούν το αρχιτεκτονικό στιλ REST. Κάθε endpoint αντιπροσωπεύει έναν πόρο και οι ενέργειες σε αυτούς τους πόρους εκτελούνται με τις τυπικές μεθόδους HTTP.

Όλα τα αιτήματα και οι αποκρίσεις του Integration API είναι σε μορφή JSON, παρέχοντας ένα συνεπές και εύχρηστο περιβάλλον για την αλληλεπίδραση με το API.

Για πλήρεις λεπτομέρειες για κάθε endpoint, συμπεριλαμβανομένων παραδειγμάτων αιτημάτων και αποκρίσεων, δείτε την τεκμηρίωση Swagger.

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

Όλα τα endpoints επιστρέφουν δεδομένα σε τυποποιημένη μορφή με τα εξής αντικείμενα:

{
  "links": {
    "self": "https://api.fabrixa.com/v2/integration/products",
    "first_page": "https://api.fabrixa.com/v2/integration/products?page=1",
    "last_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "next_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "prev_page": null
  },
  "meta": {
    "total": 2,
    "current_page": 1,
    "per_page": 10
  },
  "data": [
    {
      "id": 1,
      "name": "Product 1",
      "description": "Description of Product 1"
    },
    {
      "id": 2,
      "name": "Product 2",
      "description": "Description of Product 2"
    }
  ]
}

Περιγραφή των αντικειμένων απόκρισης

Όλα τα αιτήματα API επιστρέφουν κωδικούς κατάστασης HTTP που δίνουν πληροφορίες για την απόκριση.

Σώμα απόκρισης σφάλματος

Ένα παράδειγμα σώματος απόκρισης σφάλματος:

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/ping"
    },
    "meta": [],
    "errors": {
        "messages": [
            "Application Key is not specified."
        ]
    }
}

Το errors περιέχει λεπτομέρειες για το τι απέτυχε. Ο πίνακας messages παραθέτει τις περιγραφές των σφαλμάτων. Σε ένα Bad Request θα λάβετε τα ονόματα των πεδίων που δεν πέρασαν την επικύρωση.

Το Integration API υποστηρίζει όριο 30 αιτημάτων ανά εφαρμογή ανά λεπτό.

Αν ξεπεράσετε αυτό το όριο, θα λάβετε απόκριση 429 Too Many Requests.

Όλες οι αποκρίσεις του Integration API περιλαμβάνουν την κεφαλίδα X-RateLimit-Remaining, πόσα αιτήματα μπορεί να κάνει ακόμη ο πελάτης, και την κεφαλίδα X-RateLimit-Limit, το συνολικό επιτρεπόμενο όριο ανά λεπτό.

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

Για να δημιουργήσετε παραγγελία μέσω του Fabrixa Integration API, στείλτε αίτημα POST στο https://api.fabrixa.com/v2/integration/orders. Το σώμα του αιτήματος πρέπει να περιλαμβάνει:

Δομή σώματος αιτήματος

Δείγμα αιτήματος

{
  "number": "NL2024010201",
  "comments": "Customer agrees with a low resolution file.",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "variant_id": 2705,
      "quantity": 1,
      "client_barcode": "1234567890",
      "sources": [
        {
          "type": "file",
          "url": "https://samples-files.com/samples/sample.pdf"
        }
      ]
    }
  ],
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "3VJtP@example.com",
    "phone": "0647185332"
  },
  "shipping_address": {
    "address": "Pierre cuypershof",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0647185332"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SYZXG1585577",
    "tracking_url": "https://postnl.nl/tracktrace/3SYZXG1585577",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

Για να λάβετε την κατάσταση εκτέλεσης μιας συγκεκριμένης παραγγελίας, στείλτε αίτημα GET στο https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Η απόκριση παρέχει λίστα των εκτελέσεων που σχετίζονται με την παραγγελία, μαζί με την κατάσταση κάθε είδους, τα στοιχεία του προϊόντος και την πρόοδο των βημάτων παραγωγής.

Δείγμα απόκρισης

{
    "data": [
        {
            "id": 1499,
            "barcode": "1200004169200",
            "status": "unfulfilled",
            "created_at": "2024-08-19T12:38:59.000000Z",
            "updated_at": "2024-08-19T12:39:00.000000Z",
            "variant": {
                "id": 32327,
                "name": "Test iAPI blanket product",
                "subtitle": "100 x 150 cm",
                "SKU": "COF099191"
            },
            "product": {
                "id": 1306,
                "name": "Test iAPI blanket product",
                "subtitle": "Test iAPI blanket product"
            },
            "production_steps": [
                {
                    "id": 5,
                    "name": "Print duvet",
                    "description": "Printing the duvet according to the specified design and dimensions.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                },
                {
                    "id": 6,
                    "name": "Print pillow",
                    "description": "Printing the pillow cover with the assigned design.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                }
            ]
        }
    ]
}

Η απόκριση περιλαμβάνει λίστα εκτελέσεων, καθεμία από τις οποίες παρέχει:

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

Αν δεν επιστραφούν εκτελέσεις για μια παραγγελία, η παραγγελία δεν έχει εισέλθει ακόμη στο στάδιο επεξεργασίας.

Όταν συμπεριλαμβάνετε αρχεία προέλευσης στην παραγγελία σας, βεβαιωθείτε ότι πληρούν τις εξής απαιτήσεις:

"sources": [
    {
        "type": "file",
        "url": "https://samples-files.com/samples/source.pdf"
    }
]

Απαιτήσεις PDF και σειρά σελίδων

Η σειρά των σελίδων στο PDF έχει σημασία. Οι σελίδες αντιστοιχίζονται στα επίπεδα του προϊόντος με βάση τη θέση τους και η αναμενόμενη σειρά σελίδων εξαρτάται από τον τύπο του προϊόντος. Βεβαιωθείτε ότι οι σελίδες του PDF ακολουθούν τη σωστή σειρά επιπέδων για το προϊόν που υποβάλλετε.

Σημαντικό: κάθε σελίδα του PDF πρέπει να έχει τις απαιτούμενες διαστάσεις για το αντίστοιχο επίπεδο προϊόντος και τον σωστό προσανατολισμό. Τοποθετήστε το γραφικό ώστε το πάνω μέρος του σχεδίου να ευθυγραμμίζεται με το πάνω μέρος της σελίδας. Λανθασμένο μέγεθος ή προσανατολισμός σελίδας μπορεί να προκαλέσει προβλήματα κλιμάκωσης, περιστροφής ή ευθυγράμμισης στην παραγωγή.

Το Fabrixa Studio είναι ένα εργαλείο που επιτρέπει στους χρήστες να προσαρμόζουν και να εξατομικεύουν προϊόντα σε πραγματικό χρόνο, με ένα διαισθητικό περιβάλλον όπου μπορούν να δημιουργήσουν ή να ανεβάσουν τα δικά τους σχέδια.

Το Fabrixa Studio είναι ιδανικό για επιχειρήσεις που προσφέρουν προϊόντα κατά παραγγελία - οι πελάτες βλέπουν το σχέδιό τους πριν ολοκληρώσουν την παραγγελία.

Μπορείτε να ενσωματώσετε το Fabrixa Studio στον ιστότοπό σας μέσω ενός iframe. Έτσι οι πελάτες σας μπορούν να εξατομικεύουν προϊόντα απευθείας στον ιστότοπό σας κατά την ολοκλήρωση της αγοράς.

Παράδειγμα iframe για την ενσωμάτωση του Fabrixa Studio:

<iframe id="fabrixa-studio"
    src="https://studio.fabrixa.com?application_key={application_key}&sku={product_sku}&cart_item_key={cart_item_key}"
    name="FabrixaStudio"
    scrolling="no"
    frameborder="1"
    width="100%"
    height="100%"
    allowfullscreen="">
</iframe>

Αντικαταστήστε τις τιμές product_sku, cart_item_key και application_key με τις δικές σας δυναμικές τιμές.

• application_key - μοναδικό κλειδί για τον έλεγχο ταυτότητας στο Integration API.
• product_sku - το SKU της παραλλαγής προϊόντος, όπως ανακτάται από το Integration API.
• cart_item_key - μοναδική τιμή από την πλατφόρμα ενσωμάτωσης που προσδιορίζει το είδος καλαθιού που σχετίζεται με το προϊόν. Χρησιμοποιείται για την αποθήκευση των προσαρμογών του χρήστη, ενώ κατά τη δημιουργία της παραγγελίας εντοπίζει τις αποθηκευμένες προσαρμογές και τις αντιστοιχίζει στην παραγγελία. Δείτε το παράδειγμα παρακάτω.

Αίτημα δημιουργίας παραγγελίας με cart_item_key

{
  "number": "NL2024010201",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "sku": "SB796162",
      "quantity": 1,
      "cart_item_key": "0cb76770-de2d-4524-aa48-47b6e5f0d8a5"
    }
  ],
  "customer": {
    "...": "..."
  },
  "shipping_address": {
    "...": "..."
  },
  "shipping_label": {
    "...": "..."
  }
}

Όταν πατηθεί το κουμπί Προσθήκη στο καλάθι μέσα στο iframe, εκτελείται η εξής εντολή:

window.parent.postMessage('customizationFinished', '*');

Αντίστοιχα, όταν πατηθεί το κουμπί Πίσω:

window.parent.postMessage('closeButtonClicked', '*');

Η μέθοδος postMessage διευκολύνει την επικοινωνία μεταξύ διαφορετικών προελεύσεων για το iframe και το γονικό παράθυρο, επιτρέποντάς του να ενημερώνει το γονικό παράθυρο για συγκεκριμένες ενέργειες του χρήστη.

Το πρώτο όρισμα του postMessage είναι τα δεδομένα που θέλετε να στείλετε. Η συμβολοσειρά 'customizationFinished' δηλώνει ότι ο χρήστης ολοκλήρωσε την προσαρμογή και προσθέτει το προϊόν στο καλάθι. Το 'closeButtonClicked' δηλώνει ότι ο χρήστης επέλεξε να επιστρέψει.

Στο γονικό παράθυρο, παρακολουθήστε αυτά τα μηνύματα με έναν listener του συμβάντος message:

window.addEventListener('message', function(event) {
    if (event.origin === 'https://studio.fabrixa.com') {
        if (event.data === 'customizationFinished') {
            // Handle the Add to Cart event
            console.log('Customization finished and item can be added to cart.');
        } else if (event.data === 'closeButtonClicked') {
            // Handle the Back button event
            console.log('Back button clicked.');
        }
    }
});

Ελέγχετε πάντα το origin των εισερχόμενων μηνυμάτων για να βεβαιωθείτε ότι προέρχονται από αξιόπιστη πηγή. Ανάλογα με το μήνυμα που λαμβάνετε, εκτελέστε τις απαραίτητες ενέργειες - ενημέρωση της διεπαφής, επεξεργασία του καλαθιού και τα λοιπά. Η επικύρωση του origin είναι κρίσιμη για την ασφάλεια - εμποδίζει μη εξουσιοδοτημένα scripts να αλληλεπιδράσουν με την εφαρμογή σας.

Αφού ολοκληρωθεί η προσαρμογή, εμφανίστε το τελικό σχέδιο μέσω του παρακάτω URL προεπισκόπησης. Το URL επιστρέφει εικόνα του προσαρμοσμένου προϊόντος, κατάλληλη ως τιμή src σε ετικέτα <img>. Ιδανικό για την εμφάνιση του προσαρμοσμένου προϊόντος στο καλάθι, στη σύνοψη της παραγγελίας ή οπουδήποτε στο περιβάλλον του καταστήματός σας.

https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}

Αντικαταστήστε το {CART_ITEM_KEY} με το πραγματικό κλειδί του είδους καλαθιού και το {APPLICATION_KEY} με το έγκυρο application key σας.

Παράδειγμα χρήσης σε ετικέτα εικόνας:

<img
    src="https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}"
    alt="Customized Product Preview"
    style="max-width: 100%; height: auto;" />

Η Fabrixa χρησιμοποιεί webhooks για να ενημερώνει το σύστημά σας για συμβάντα σε πραγματικό χρόνο - ενημερώσεις ή δημιουργίες παραγγελιών. Όταν συμβεί ένα γεγονός, η Fabrixa στέλνει στον διακομιστή σας ένα webhook με τις σχετικές πληροφορίες. Ο διακομιστής σας πρέπει να διαθέτει δημόσιο endpoint POST για τη διαχείριση των εισερχόμενων webhooks.

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

{
  "content-type": "application/json",
  "x-webhook-signature": "YmEwNjBhMGMyMzE3ZWQ5NGQ5NDYwOGVhNzNhMjQ4M2MyODZkZmI3NTQ1YzYxYjdkMzNhZjgzYzBmMTkxYTAxMw==",
  "x-webhook-topic": "order.updated"
}

Ανάλυση κεφαλίδων

• content-type - για τα webhooks είναι πάντα application/json.
• x-webhook-signature - η υπογραφή HMAC-SHA256 για την επαλήθευση του αιτήματος.
• x-webhook-topic - ο τύπος συμβάντος ή το θέμα του webhook. Για παράδειγμα:
  • order.created - ενεργοποιείται όταν δημιουργείται νέα παραγγελία.
  • order.updated - ενεργοποιείται όταν ενημερώνεται υπάρχουσα παραγγελία.

Τα webhooks της Fabrixa ενημερώνουν το σύστημά σας για αλλαγές στην κατάσταση ή τη δραστηριότητα μιας παραγγελίας. Κάθε webhook ενεργοποιείται από μια συγκεκριμένη τιμή x-webhook-topic. Τα θέματα που υποστηρίζονται σήμερα:

Καταστάσεις παραγγελίας

• Completed - η παραγγελία απεστάλη ή παραλήφθηκε και η παραλαβή έχει επιβεβαιωθεί. Για ψηφιακά προϊόντα, ο πελάτης έχει πληρώσει και τα αρχεία είναι διαθέσιμα για λήψη.
• Canceled - ο πελάτης ακύρωσε την πληρωμή, η συναλλαγή δεν ολοκληρώθηκε.
• On hold - η παραγγελία είναι προσωρινά σε αναστολή.
• Imported - η παραγγελία εισήχθη στην πλατφόρμα.

Καταστάσεις εκτέλεσης

• Unfulfilled - η παραγγελία δεν έχει προετοιμαστεί ούτε αποσταλεί ακόμη.
• Partially fulfilled - ορισμένα είδη έχουν επεξεργαστεί ή αποσταλεί, τα υπόλοιπα εκκρεμούν.
• Scheduled - η παραγγελία έχει προγραμματιστεί για επεξεργασία.
• Rejected - το αίτημα εκτέλεσης απορρίφθηκε, συχνά λόγω μη έγκυρων στοιχείων παραγγελίας ή μη διαθεσιμότητας.
• Fulfilled - η παραγγελία επεξεργάστηκε πλήρως και παραδόθηκε ή διατέθηκε στον πελάτη.

Ένα παράδειγμα του payload που αποστέλλεται με το webhook. Αυτό το payload αντιπροσωπεύει ενημέρωση παραγγελίας:

{
  "id": 23069,
  "number": "1250211835",
  "comments": null,
  "is_archived": false,
  "status": "imported",
  "fulfillment_status": "unfulfilled",
  "purchased_at": "2025-04-17T16:17:21.000000Z",
  "created_at": "2025-04-17T16:17:23.000000Z",
  "updated_at": "2025-04-18T07:43:52.000000Z",
  "rows": [
    {
      "id": 27954,
      "quantity": 1,
      "client_barcode": "1250211835",
      "fulfillment_status": "unfulfilled",
      "variant": {
        "id": 293457,
        "name": "Sherpa fleece deken",
        "subtitle": "100x150",
        "SKU": "SFD787231",
        "product": {
          "id": 5319,
          "name": "Sherpa fleece deken",
          "subtitle": "Sherpa fleece deken"
        }
      },
      "sources": [
        {
          "type": "print",
          "url": "https://storage.googleapis.com/fabrixa-api/storage/99b10aaa-df4d-47e4-9bc9-b1d6a785df4c/orders/merchandise-sources/120002795400.pdf",
          "properties": {
            "fill_style": "contain"
          }
        }
      ]
    }
  ]
}

Για να βεβαιωθείτε ότι το αίτημα webhook είναι αυθεντικό και δεν έχει αλλοιωθεί, επαληθεύστε την κεφαλίδα x-webhook-signature. Αυτό σημαίνει ότι υπολογίζετε ξανά την υπογραφή HMAC-SHA256 με βάση το ανεπεξέργαστο payload του αιτήματος και το μυστικό κλειδί σας, και τη συγκρίνετε με την υπογραφή που λάβατε.

Παράδειγμα σε καθαρή PHP

$payload = file_get_contents('php://input');
$yourSecret = 'your-secret-key';
$expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
$receivedSignature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Παράδειγμα σε Laravel

public function handle(Request $request)
{
    $yourSecret = 'your-secret-key';
    $payload = $request->getContent();
    $expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
    $receivedSignature = $request->header('x-webhook-signature');

    if (!hash_equals($expectedSignature, $receivedSignature)) {
        abort(403, 'Invalid signature');
    }

    // Continue processing...
}

Αντικαταστήστε το $yourSecret με το κοινό μυστικό κλειδί σας. Χρησιμοποιείτε πάντα hash_equals για τη σύγκριση υπογραφών, ώστε να περιορίσετε τις επιθέσεις χρονισμού.

Τα webhooks απενεργοποιούνται από προεπιλογή μετά από 10 αποτυχημένες προσπάθειες παράδοσης. Αν το endpoint σας επιστρέψει κατάσταση αποτυχίας, όπως 404 ή οποιοδήποτε σφάλμα 5xx, το webhook θα επαναληφθεί συνολικά 10 φορές. Αν συνεχίσει να επιστρέφει κωδικό απόκρισης εκτός 2xx ή 3xx, θα απενεργοποιηθεί. Στις επιτυχείς αποκρίσεις περιλαμβάνονται:

• 2xx - υποδηλώνει επιτυχή επεξεργασία, π.χ. 200 OK.
• 301 και 302 - αποκρίσεις ανακατεύθυνσης που υποδηλώνουν ότι το webhook διαχειρίστηκε ή προωθήθηκε επιτυχώς.

Συνιστούμε ανεπιφύλακτα το endpoint σας να επιστρέφει κωδικό κατάστασης 200 OK όσο το δυνατόν γρηγορότερα, ώστε να επιβεβαιώνει την επιτυχή λήψη του webhook. Παρότι κάθε απόκριση 2xx ή 3xx θεωρείται επιτυχής, ο 200 είναι ο πιο συνηθισμένος και αξιόπιστος.

Για να αποφύγετε λήξεις χρόνου παράδοσης ή επαναλήψεις, επιστρέψτε αμέσως 200 OK και επεξεργαστείτε το payload του webhook ασύγχρονα, για παράδειγμα μέσω εργασίας παρασκηνίου ή ουράς. Αν το endpoint σας καθυστερεί πολύ να αποκριθεί, μπορεί να θεωρηθεί αποτυχία, ακόμη και αν τελικά η απόκριση είναι επιτυχής.

Αποκρίσεις με κωδικούς κατάστασης στο εύρος 4xx ή 5xx, καθώς και λήξεις χρόνου, ενεργοποιούν επαναλήψεις σύμφωνα με τον μηχανισμό επαναλήψεων.