Τεκμηρίωση του 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, το συνολικό επιτρεπόμενο όριο ανά λεπτό.

Η λειτουργία sandbox σάς επιτρέπει να δοκιμάσετε την ενσωμάτωσή σας από άκρη σε άκρη, προτού παραχθεί ή χρεωθεί οποιαδήποτε πραγματική παραγγελία. Ισχύει για ολόκληρο τον λογαριασμό σας: οι παραγγελίες από όλα τα κανάλια πωλήσεων, συμπεριλαμβανομένων του Integration API και των συνδεδεμένων καταστημάτων Shopify και WooCommerce, δεν παράγονται και δεν χρεώνονται στο υπόλοιπό σας. Ο λογαριασμός σας βρίσκεται σε λειτουργία sandbox όσο η κατάστασή του είναι σε αναμονή ενεργοποίησης.

Σε λειτουργία sandbox μπορείτε να:

• συνδέσετε το κατάστημά σας Shopify ή WooCommerce ή να δημιουργήσετε ένα κανάλι Integration API·
• προσθέσετε προϊόντα και να ελέγξετε τιμές και εκτιμήσεις αποστολής·
• εισαγάγετε, δημιουργήσετε, ενημερώσετε και ακυρώσετε παραγγελίες·
• διαπιστώσετε ότι καμία από αυτές τις παραγγελίες δεν παράγεται ούτε χρεώνεται στο υπόλοιπό σας·
• επαληθεύσετε την παράδοση των webhooks και τις υπογραφές.

Για να δοκιμάσετε παραγγελίες, προσθέστε προϊόντα από τον κατάλογο της Fabrixa: ανοίξτε ένα προϊόν, πατήστε Πουλήστε το και επιλέξτε παραλλαγές και σχέδια. Στη συνέχεια εμφανίζονται στην ενότητα Τα προϊόντα μου.

Για να μεταβείτε σε λειτουργία sandbox, ανοίξτε το Platform, μεταβείτε στο Ρυθμίσεις → Εταιρεία → Λειτουργία sandbox και πατήστε Μετάβαση σε λειτουργία sandbox. Μπορείτε επίσης να την ενεργοποιήσετε όταν προσθέτετε νέο κανάλι πωλήσεων, συμπεριλαμβανομένου καναλιού Integration API, ή να στείλετε email στο support@fabrixa.com και θα μεταφέρουμε εμείς τον λογαριασμό σας. Η λειτουργία sandbox είναι διαθέσιμη μόνο σε ενεργούς λογαριασμούς.

Όταν είστε έτοιμοι, ενεργοποιήστε μόνοι σας τον λογαριασμό σας στο Platform, στο Ρυθμίσεις → Εταιρεία → Λειτουργία sandbox. Μπορείτε επίσης να στείλετε email στο support@fabrixa.com και θα τον ενεργοποιήσουμε εμείς. Τα συνδεδεμένα καταστήματα και τα διαπιστευτήρια API συνεχίζουν να λειτουργούν, επομένως δεν χρειάζεται να ρυθμίσετε τίποτα ξανά.

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

Ο κατάλογος είναι ό,τι παράγει η Fabrixa. Τα προϊόντα σας είναι τα προϊόντα του καταλόγου που προσθέσατε στον λογαριασμό σας στη Fabrixa, με δικά σας ονόματα, περιγραφές, εικόνες και SKU. Μια γραμμή παραγγελίας αναφέρεται σε μια παραλλαγή προϊόντος - ένα μέγεθος ή μια έκδοση ενός προϊόντος - μέσω του sku ή του variant_id της: σε παραλλαγή ενός από τα προϊόντα σας ή σε παραλλαγή του καταλόγου που παραγγέλνεται απευθείας.

Για να λάβετε τη λίστα των προϊόντων που παράγει η Fabrixa, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/catalog/products με τα διαπιστευτήριά σας. Περιλαμβάνει τα ενεργά προϊόντα που έχουν παραλλαγή την οποία παράγει αυτή τη στιγμή ένας συνεργάτης εκτύπωσης, και μόνο αυτές τις παραλλαγές, καθεμία με το SKU, την τιμή πώλησης, τις διαστάσεις και τις τιμές επιλογών της.

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

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

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/products?category_id=19&limit=10' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/products",
        "first_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "last_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 1305,
            "name": "Duvet Cover",
            "subtitle": "Duvet Cover with a pillow",
            "description": "
Soft personalized duvet cover.
",
            "slug": "duvet-cover",
            "code": "DUVET-001",
            "HS_code": "63023100",
            "created_at": "2024-08-16T09:32:07.000000Z",
            "updated_at": "2024-08-16T09:38:50.000000Z",
            "is_sellable": true,
            "variants_min_selling_price": "29.95",
            "variants_max_selling_price": "49.95",
            "type": {
                "id": 5,
                "name": "Duvet cover"
            },
            "status": {
                "id": 2,
                "name": "Active"
            },
            "categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "parent_category": {
                        "id": 8,
                        "name": "Bedroom",
                        "description": "Bedroom products"
                    }
                }
            ],
            "images": [
                {
                    "id": 5566,
                    "url": "https://storage.googleapis.com/example/catalog/duvet-cover.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "COT864311",
                    "selling_price": "29.95",
                    "width": "140.00",
                    "height": "200.00",
                    "length": "2.00",
                    "weight": "1.20",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:36:37.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": 2708,
                    "name": "Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "COT864314",
                    "selling_price": "49.95",
                    "width": "200.00",
                    "height": "220.00",
                    "length": "2.00",
                    "weight": "1.80",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:37:11.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Πεδία απόκρισης

Για να λάβετε τις κατηγορίες στις οποίες είναι οργανωμένος ο κατάλογος, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/catalog/categories με τα διαπιστευτήριά σας. Η απόκριση περιέχει τις κατηγορίες ανώτατου επιπέδου, καθεμία με τις υποκατηγορίες της ένθετες στο sub_categories και το πλήθος των προϊόντων καταλόγου που περιέχει στο products_count. Περάστε το id μιας κατηγορίας ως category_id όταν περιηγείστε στον κατάλογο, ή το id μιας κατηγορίας ανώτατου επιπέδου ως parent_category_id για να λάβετε με μία κίνηση τα προϊόντα όλων των υποκατηγοριών της.

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

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

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/categories?with_products_only=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/categories"
    },
    "meta": {
        "total": 1
    },
    "data": [
        {
            "id": 8,
            "name": "Bedroom",
            "description": "Bedroom products",
            "sort_number": 1,
            "slug": "bedroom",
            "products_count": 12,
            "sub_categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "sort_number": 1,
                    "slug": "duvet-covers",
                    "products_count": 7,
                    "images": [],
                    "sub_categories": []
                },
                {
                    "id": 20,
                    "name": "Pillows",
                    "description": "Personalized pillows and pillowcases",
                    "sort_number": 2,
                    "slug": "pillows",
                    "products_count": 4,
                    "images": [],
                    "sub_categories": []
                }
            ],
            "parent_category": null,
            "images": [
                {
                    "id": 781,
                    "url": "https://storage.googleapis.com/example/catalog/bedroom.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ]
        }
    ]
}

Για να λάβετε τα προϊόντα του λογαριασμού σας, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/products με τα διαπιστευτήριά σας. Τα προϊόντα σας είναι τα προϊόντα του καταλόγου που προσθέσατε στον λογαριασμό σας στη Fabrixa: φέρουν τα ονόματα, τις περιγραφές και τις εικόνες που τους δώσατε εκεί, και οι παραλλαγές τους τις τιμές SKU που επιλέξατε. Εμφανίζονται μόνο τα ενεργά προϊόντα, δέκα ανά σελίδα εκτός αν περάσετε limit.

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

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

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

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

{
    "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=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "slug": "dreamy-duvet-cover",
            "width": "50.00",
            "height": "50.00",
            "length": "20.00",
            "weight": "100.00",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z",
            "type": {
                "id": 5,
                "name": "Duvet cover",
                "description": "Duvet cover with pillow"
            },
            "available_options": [
                {
                    "id": 151,
                    "name": "Duvet Size",
                    "values": [
                        {
                            "id": 471,
                            "value": "140x200"
                        },
                        {
                            "id": 474,
                            "value": "200x220"
                        }
                    ]
                }
            ],
            "categories": [
                {
                    "id": 912,
                    "name": "Bedding"
                }
            ],
            "collections": [
                {
                    "id": 77,
                    "name": "Spring 2025"
                }
            ],
            "images": [
                {
                    "id": 48120,
                    "is_main": true,
                    "image_size": "1200x1200",
                    "url": "https://storage.googleapis.com/example/shop/dreamy-duvet-cover.jpg",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 32323,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "DDC-140200",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                },
                {
                    "id": 32326,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "DDC-200220",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                }
            ]
        }
    ]
}

Για να διαβάσετε ένα μεμονωμένο προϊόν, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/products/{product_id}, όπου {product_id} είναι το id του. Η απόκριση περιέχει τα ίδια πεδία με τη λίστα. Ένα προϊόν που δεν βρίσκεται στον λογαριασμό σας, ακόμη και προϊόν καταλόγου, απαντά με 404 Not Found και το μήνυμα Product not found.

Πεδία απόκρισης

Μια παραλλαγή είναι μία έκδοση ενός προϊόντος που μπορεί να παραγγελθεί - ένα μέγεθος, ένα χρώμα - και είναι αυτό στο οποίο αναφέρεται μια γραμμή παραγγελίας, μέσω sku ή variant_id. Για να διαβάσετε μια παραλλαγή ενός από τα προϊόντα σας, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/variants/{variant_id}, όπου {variant_id} είναι το id της. Μια παραλλαγή προϊόντος που δεν βρίσκεται στον λογαριασμό σας απαντά με 404 Not Found και το μήνυμα Variant not found.

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

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

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/variants/32323"
    },
    "meta": [],
    "data": {
        "id": 32323,
        "name": "Dreamy Duvet Cover",
        "subtitle": "140x200",
        "description": null,
        "SKU": "DDC-140200",
        "created_at": "2025-03-04T10:12:41.000000Z",
        "updated_at": "2025-03-04T10:12:41.000000Z",
        "width": "140.00",
        "height": "200.00",
        "length": "2.00",
        "weight": "1.20",
        "options": [
            {
                "id": 151,
                "name": "Duvet Size",
                "values": [
                    {
                        "id": 471,
                        "value": "140x200"
                    }
                ]
            }
        ],
        "images": [],
        "product": {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "description2": null,
            "slug": "dreamy-duvet-cover",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z"
        },
        "available_source_types": ["duvet", "pillow", "pillow-back"],
        "required_source_types": ["duvet", "pillow"]
    }
}

Πεδία απόκρισης

Μια γραμμή παραγγελίας για αυτή την παραλλαγή, με ένα PDF του οποίου οι σελίδες είναι τα επίπεδά της:

"rows": [
    {
        "sku": "DDC-140200",
        "quantity": 1,
        "sources": [
            {
                "type": "file",
                "url": "https://samples-files.com/samples/duvet-cover.pdf"
            }
        ]
    }
]

Ποιες παραλλαγές μπορούν να παραγγελθούν

Δημιουργήστε παραγγελίες στη 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": "0612345678"
  },
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SABCD1234567",
    "tracking_url": "https://postnl.nl/tracktrace/3SABCD1234567",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-26T21:15:04.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

Για να ενημερώσετε μια παραγγελία, στείλτε αίτημα PATCH στο https://api.fabrixa.com/v2/integration/orders/{order_id}, όπου {order_id} είναι το αναγνωριστικό της παραγγελίας στο Fabrixa. Αλλάζουν μόνο τα πεδία που στέλνετε και η κατάσταση της παραγγελίας παραμένει ίδια. Η απάντηση περιέχει την ενημερωμένη παραγγελία. Μπορείτε να αλλάξετε:

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

{
  "comments": "Deliver to the neighbours if nobody is home.",
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "19",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  }
}

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Deliver to the neighbours if nobody is home.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T09:41:18.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "19",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "errors": {
        "rows": [
            "Order rows cannot be changed. Cancel the order and create a new one."
        ]
    }
}

Για να ακυρώσετε μια παραγγελία, στείλτε αίτημα POST χωρίς σώμα στο https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, όπου {order_id} είναι το αναγνωριστικό της παραγγελίας στο Fabrixa (το αριθμητικό πεδίο id της παραγγελίας) και όχι ο δικός σας αριθμός παραγγελίας. Η απάντηση περιέχει την παραγγελία με την κατάσταση canceled και αποστέλλεται webhook order.updated.

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "canceled",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T10:02:45.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

Αν η παραγγελία δεν μπορεί να ακυρωθεί, το API απαντά με 412 Precondition Failed και ένα μήνυμα με τον λόγο: η τρέχουσα κατάστασή της δεν το επιτρέπει (η κατάσταση αναφέρεται στο μήνυμα) ή η παραγωγή έχει ήδη ξεκινήσει.

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "errors": {
        "messages": [
            "This order cannot be canceled in its current status (ready for shipping)."
        ]
    }
}

Μια παραγγελία παρακολουθείται μέσω τριών καταστάσεων: του πεδίου status της παραγγελίας, της κατάστασης παραγωγής της fulfillment_status και του πεδίου status κάθε αποστολής στο shipments. Κάθε αλλαγή αποστέλλεται στο webhook order.updated και επιστρέφεται από το GET /orders/{order_id}.

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

Οι τιμές του πεδίου status μιας παραγγελίας, με τη σειρά που εμφανίζονται:

• imported - η παραγγελία παραλήφθηκε μέσω του API. Κάθε παραγγελία ξεκινά από εδώ.
• on hold - το υπόλοιπο δεν καλύπτει το κόστος της παραγγελίας. Μόλις αναπληρωθεί, η παραγγελία επιστρέφει σε imported και συνεχίζει.
• accepted - η παραγγελία έγινε αποδεκτή και αποστέλλεται στην παραγωγή.
• completed (τελική) - όλα τα είδη έχουν παραχθεί.
• canceled (τελική) - η παραγγελία ακυρώθηκε. Αυτό είναι δυνατό όσο βρίσκεται σε imported, accepted ή on hold και η παραγωγή δεν έχει ξεκινήσει ακόμη.

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

Οι τιμές του πεδίου fulfillment_status μιας παραγγελίας και κάθε γραμμής της, με τη σειρά που εμφανίζονται. Κινείται μόνο προς τα εμπρός, ποτέ προς τα πίσω:

• unfulfilled - η παραγωγή δεν έχει ξεκινήσει.
• scheduled - η παραγγελία έχει προγραμματιστεί σε παρτίδα παραγωγής. Από εδώ και πέρα δεν μπορεί πλέον να ακυρωθεί.
• processing - η παραγωγή βρίσκεται σε εξέλιξη.
• partially fulfilled - ορισμένα είδη είναι έτοιμα, τα υπόλοιπα βρίσκονται ακόμη στην παραγωγή.
• fulfilled (τελική) - όλα τα είδη είναι έτοιμα. Το status της παραγγελίας γίνεται τότε completed.

Μια παραγγελία στο σύνολό της δεν απορρίπτεται ποτέ. Ένα μεμονωμένο είδος μπορεί να απορριφθεί στον ποιοτικό έλεγχο κατά την παραγωγή. Τότε τυπώνεται ξανά: επιστρέφει σε unfulfilled και περνά ξανά από την παραγωγή, ενώ η παραγγελία διατηρεί την κατάστασή της και συνεχίζει μόλις το είδος είναι έτοιμο.

Καταστάσεις αποστολής

Οι τιμές του πεδίου status κάθε αποστολής στο shipments, με τη σειρά που εμφανίζονται:

• pending - η αποστολή προετοιμάζεται.
• registered - η ετικέτα δημιουργήθηκε στη μεταφορική.
• collected - η μεταφορική παρέλαβε το δέμα.
• in transit - το δέμα είναι σε μεταφορά.
• delivered (τελική) - το δέμα παραδόθηκε.

Εξαιρέσεις:

• failed - η μεταφορική ανέφερε πρόβλημα.
• returned (τελική) - το δέμα επιστράφηκε σε εμάς.
• canceled (τελική) - η αποστολή ακυρώθηκε.

Για να λάβετε την κατάσταση εκτέλεσης μιας συγκεκριμένης παραγγελίας, στείλτε αίτημα 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 τιμολογεί την ίδια την παραγγελία.

Για να μάθετε σε ποιες χώρες μπορεί να αποσταλεί μια παραλλαγή προϊόντος, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/shipping/countries με τα διαπιστευτήριά σας. Η λίστα περιέχει, ταξινομημένες κατά όνομα, τις χώρες προς τις οποίες η τοποθεσία που παράγει την παραλλαγή έχει χρέωση αποστολής για ένα δέμα αποστολής στο οποίο μπορεί να συσκευαστεί η παραλλαγή. Μια χώρα που δεν περιλαμβάνεται στη λίστα δεν έχει χρέωση αποστολής για την παραλλαγή.

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

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

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/countries?sku=DDC-140200' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/countries"
    },
    "meta": {
        "total": 2
    },
    "data": [
        {
            "code": "BE",
            "name": "Belgium",
            "min_shipping_price": "7.75",
            "max_shipping_price": "9.85",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 2
        },
        {
            "code": "NL",
            "name": "Netherlands",
            "min_shipping_price": "6.70",
            "max_shipping_price": "8.40",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 1
        }
    ]
}

Πεδία απόκρισης

Για να μάθετε πόσο θα κόστιζε η αποστολή μιας παραλλαγής προϊόντος και πόσο θα διαρκούσε η μεταφορά της, στείλτε ένα αίτημα GET στο https://api.fabrixa.com/v2/integration/shipping/estimate με τα διαπιστευτήριά σας. Η εκτίμηση ακολουθεί τους κανόνες με τους οποίους υπολογίζεται η τιμή μιας παραγγελίας: τα τεμάχια συσκευάζονται στα δέματα αποστολής της τοποθεσίας που παράγει την παραλλαγή, και η τιμή κάθε δέματος υπολογίζεται βάσει της διαδρομής από αυτή την τοποθεσία έως τη χώρα προορισμού. Τίποτα δεν παραγγέλνεται ούτε δεσμεύεται, και η τιμή μιας παραγγελίας υπολογίζεται τη στιγμή που υποβάλλεται, οπότε το κόστος αποστολής της μπορεί να διαφέρει αν στο μεταξύ αλλάξουν οι χρεώσεις αποστολής.

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

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

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/estimate?sku=DDC-140200&country_code=NL&quantity=2' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

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

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/estimate"
    },
    "meta": [],
    "data": {
        "variant_id": 32323,
        "sku": "DDC-140200",
        "quantity": 2,
        "country_code": "NL",
        "origin_country": {
            "code": "PT",
            "name": "Portugal"
        },
        "packages_count": 1,
        "packages": [
            {
                "package_type": "Small Box",
                "length": 30,
                "width": 20,
                "height": 10,
                "quantity": 1,
                "price": "7.45",
                "eta_days": 3
            }
        ],
        "shipping_price": "7.45",
        "currency": "EUR",
        "eta_days": 3
    }
}

Πεδία απόκρισης

Σε ένα αίτημα που δεν περνά την επικύρωση η απόκριση είναι 400 Bad Request με τον λόγο για κάθε πεδίο, με τα ίδια μηνύματα όπως για μια γραμμή παραγγελίας, για παράδειγμα The variant not found. Όταν κανένα δέμα αποστολής δεν μπορεί να χωρέσει τα τεμάχια, η απόκριση είναι 400 Bad Request με το μήνυμα No shipping package can carry the variant.

Το 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 - μοναδική τιμή από την πλατφόρμα ενσωμάτωσης που προσδιορίζει το είδος καλαθιού που σχετίζεται με το προϊόν. Χρησιμοποιείται για την αποθήκευση των προσαρμογών του χρήστη, ενώ κατά τη δημιουργία της παραγγελίας εντοπίζει τις αποθηκευμένες προσαρμογές και τις αντιστοιχίζει στην παραγγελία. Δείτε το παράδειγμα παρακάτω.
• locale (προαιρετικό) - η γλώσσα του περιβάλλοντος του Studio και των μηνυμάτων σφάλματός του, π.χ. de_DE ή de. Χωρίς αυτό, το Studio ανοίγει στη γλώσσα του προγράμματος περιήγησης του αγοραστή, αν υποστηρίζεται, διαφορετικά στα αγγλικά.

Η κεφαλίδα του Studio δείχνει το όνομα του προϊόντος όπως είναι στο κατάστημά σας - τον ίδιο τίτλο που βλέπουν οι πελάτες σας - και από κάτω τις επιλογές της επιλεγμένης παραλλαγής. Είναι το δικό σας αντίγραφο του προϊόντος στο κατάστημα, οπότε ένα όνομα που αλλάζετε στο Fabrixa εμφανίζεται και στο Studio· το locale δεν το μεταφράζει.

Αίτημα δημιουργίας παραγγελίας με 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",
  "user-agent": "Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)",
  "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 αποστέλλονται με το User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)· αν το endpoint σας φιλτράρει την αυτοματοποιημένη κίνηση, επιτρέψτε το. Για να βεβαιωθείτε ότι ένα αίτημα προέρχεται από το Fabrixa, επαληθεύστε το x-webhook-signature.

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

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

{
  "id": 23069,
  "number": "1250211835",
  "comments": null,
  "is_archived": false,
  "status": "accepted",
  "fulfillment_status": "fulfilled",
  "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": "fulfilled",
      "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"
          }
        }
      ]
    }
  ],
  "shipments": [
    {
      "id": 4182,
      "carrier": "PostNL",
      "method": "Standard",
      "status": "registered",
      "tracking_number": "3SABCD1234567",
      "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB",
      "packages": [
        {
          "tracking_number": "3SABCD1234567",
          "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB"
        }
      ],
      "expected_delivery_date": "2025-04-22",
      "created_at": "2025-04-18T07:43:50.000000Z"
    }
  ]
}

Μόλις αποσταλεί η παραγγελία, το shipments περιέχει κάθε αποστολή με τη μεταφορική της (carrier), τη μέθοδο αποστολής (method), την κατάσταση (status: pending, registered, collected, in transit, delivered, failed, returned ή canceled) και την παρακολούθηση: tracking_number και tracking_url, και τα ίδια για κάθε δέμα στο packages όταν μια αποστολή έχει περισσότερα. Αποστέλλεται webhook order.updated κάθε φορά που αλλάζει η κατάσταση ή η παρακολούθηση μιας αποστολής, και το GET /orders/{order_id} επιστρέφει το ίδιο πεδίο.

Για να βεβαιωθείτε ότι το αίτημα 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, καθώς και λήξεις χρόνου, ενεργοποιούν επαναλήψεις σύμφωνα με τον μηχανισμό επαναλήψεων.