Fabrixa Integration API dokumentatsioon

Integration API-le ligipääsuks autendi oma päringud nii rakenduse ligipääsuvõtme (access token) kui ka rakenduse võtmega:

Authorization-päis

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Rakenduse võtme päis

X-Application-Key: APPLICATION_KEY

cURL-käsu näidis

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'

Asenda APPLICATION_ACCESS_TOKEN oma tegeliku ligipääsuvõtmega ja APPLICATION_KEY oma tegeliku rakenduse võtmega.

Integration API lõpp-punktid on korraldatud ressursitüübi järgi ja järgivad REST-arhitektuuri stiili. Iga lõpp-punkt esindab ressurssi ning toiminguid nende ressurssidega tehakse tavapäraste HTTP-meetoditega.

Kõik Integration API päringud ja vastused on JSON-vormingus, mis annab API-ga suhtlemiseks ühtse ja hõlpsasti kasutatava liidese.

Iga lõpp-punkti täielikud üksikasjad koos päringu- ja vastusenäidetega leiad meie Swaggeri dokumentatsioonist.

Vastuse vorming

Kõik lõpp-punktid tagastavad andmed ühtses vormingus järgmiste objektidega:

{
  "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"
    }
  ]
}

Vastuse objektide kirjeldus

Kõik API päringud tagastavad HTTP olekukoodid, mis annavad vastuse kohta selgust.

Veavastuse keha

Veavastuse keha näidis:

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

errors sisaldab üksikasju selle kohta, mis ebaõnnestus. Massiiv messages loetleb vigade kirjeldused. Bad Requesti korral saad nende väljade nimed, mis valideerimise läbi ei teinud.

Integration API toetab piirangut 30 päringut rakenduse kohta minutis.

Selle piirangu ületamisel saad vastuse 429 Too Many Requests.

Kõik Integration API vastused sisaldavad päist X-RateLimit-Remaining, mis näitab, mitu päringut klient veel teha saab, ning päist X-RateLimit-Limit, mis näitab minutis lubatud koguarvu.

Liivakastirežiim võimaldab testida integratsiooni algusest lõpuni enne, kui ükski päris tellimus valmistatakse või tasutakse. See kehtib kogu teie kontole: tellimusi kõigist müügikanalitest, sh Integration API ja ühendatud Shopify ning WooCommerce’i poodidest, ei valmistata ega arvata teie saldost maha. Teie konto on liivakastirežiimis seni, kuni selle olek on ootab aktiveerimist.

Liivakastirežiimis saate:

• ühendada oma Shopify või WooCommerce’i poe või luua Integration API kanali;
• lisada tooteid ning kontrollida hindu ja tarnehinnangud;
• importida, luua, muuta ja tühistada tellimusi;
• veenduda, et ühtegi neist tellimustest ei valmistata ega arvata saldost maha;
• kontrollida veebihaakide kohaletoimetamist ja allkirju.

Tellimuste testimiseks lisage tooteid Fabrixa kataloogist: avage toode, klõpsake Müü seda ja valige variandid ning kujundused. Seejärel ilmuvad need jaotisse Minu tooted.

Konto liivakastirežiimi lülitamiseks avage Platform, minge jaotisse Seaded → Ettevõte → Liivakastirežiim ja klõpsake Lülita liivakastirežiimi. Selle saab sisse lülitada ka uue müügikanali, sh Integration API kanali lisamisel, või kirjutada aadressile support@fabrixa.com, ja me lülitame teie konto teie eest. Liivakastirežiim on saadaval ainult aktiivsetele kontodele.

Kui olete valmis, aktiveerige konto ise Platformis jaotises Seaded → Ettevõte → Liivakastirežiim. Võite ka kirjutada aadressile support@fabrixa.com, ja me aktiveerime selle teie eest. Ühendatud poed ja API kasutajaandmed jätkavad tööd, seega pole midagi vaja uuesti seadistada.

Pärast aktiveerimist lähevad kõik uued tellimused tootmisse ja arvatakse teie saldost maha. Enne aktiveerimist loodud tellimused jäävad testtellimusteks: neid ei valmistata ega arvata kunagi maha, isegi mitte pärast aktiveerimist.

Kataloog on kõik, mida Fabrixa toodab. Teie tooted on kataloogi tooted, mille olete oma Fabrixa kontole lisanud, oma nimede, kirjelduste, piltide ja SKU-dega. Tellimuse rida viitab toote variandile - toote ühele suurusele või versioonile - selle sku või variant_id kaudu: mõne teie toote variandile või otse tellitavale kataloogi variandile.

Fabrixa toodetavate toodete loendi saamiseks saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/catalog/products oma tunnustega. See loetleb aktiivsed tooted, millel on variant, mida trükipartner praegu toodab, ja ainult need variandid, igaüks oma SKU, müügihinna, mõõtmete ja valikute väärtustega.

Päringu parameetrid

Päringu näidis

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'

Vastuse näidis

{
    "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"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Vastuse väljad

Kataloogi kategooriate loendi saamiseks saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/catalog/categories oma tunnustega. Vastus sisaldab ülataseme kategooriaid, igaüks oma alamkategooriatega väljal sub_categories ja selles sisalduvate kataloogi toodete arvuga väljal products_count. Kataloogi sirvides edastage kategooria id parameetrina category_id või ülataseme kategooria id parameetrina parent_category_id, et saada korraga kõigi selle alamkategooriate tooted.

Päringu parameetrid

Päringu näidis

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'

Vastuse näidis

{
    "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
                }
            ]
        }
    ]
}

Oma konto toodete loendi saamiseks saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/products oma tunnustega. Teie tooted on kataloogi tooted, mille olete oma Fabrixa kontole lisanud: neil on nimed, kirjeldused ja pildid, mille te neile seal andsite, ja nende variantidel teie valitud SKU väärtused. Loendis on ainult aktiivsed tooted, kümme lehel, kui te ei edasta limit väärtust.

Päringu parameetrid

Päringu näidis

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'

Vastuse näidis

{
    "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"]
                }
            ]
        }
    ]
}

Ühe toote lugemiseks saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/products/{product_id}, kus {product_id} on selle id. Vastus sisaldab samu välju mis loend. Toode, mida teie kontol pole, isegi kataloogi toode, vastab 404 Not Found ja sõnumiga Product not found.

Vastuse väljad

Variant on toote üks tellitav versioon - üks suurus, üks värv - ja see, millele tellimuse rida viitab sku või variant_id kaudu. Mõne oma toote variandi lugemiseks saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/variants/{variant_id}, kus {variant_id} on selle id. Sellise toote variant, mida teie kontol pole, vastab 404 Not Found ja sõnumiga Variant not found.

Päringu näidis

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'

Vastuse näidis

{
    "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"]
    }
}

Vastuse väljad

Tellimuse rida selle variandi jaoks PDF-iga, mille leheküljed on selle kihid:

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

Milliseid variante saab tellida

Loo Fabrixas tellimusi oma poest või platvormilt, lisa nõutud trükifailid ja jälgi iga üksust, kui see läbib täitmise etapid.

Tellimuse loomiseks Fabrixa Integration API kaudu saada POST-päring aadressile https://api.fabrixa.com/v2/integration/orders. Päringu keha peab sisaldama:

Päringu keha struktuur

Päringu näidis

{
  "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"
  }
}

Vastuse näidis

{
    "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"
        }
    }
}

Tellimuse uuendamiseks saada PATCH-päring aadressile https://api.fabrixa.com/v2/integration/orders/{order_id}, kus {order_id} on tellimuse Fabrixa ID. Muudetakse ainult saadetud välju ja tellimuse olek jääb samaks. Vastus sisaldab uuendatud tellimust. Muuta saab:

Päringu näidis

{
  "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"
  }
}

Vastuse näidis

{
    "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."
        ]
    }
}

Tellimuse tühistamiseks saada ilma kehata POST-päring aadressile https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, kus {order_id} on tellimuse Fabrixa ID (tellimuse numbriline väli id), mitte teie tellimuse number. Vastus sisaldab tellimust olekuga canceled ja saadetakse order.updated webhook.

Vastuse näidis

{
    "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"
        }
    }
}

Kui tellimust ei saa tühistada, vastab API koodiga 412 Precondition Failed ja põhjust selgitava sõnumiga: selle praegune olek ei luba seda (olek on sõnumis nimetatud) või tootmine on juba alanud.

{
    "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)."
        ]
    }
}

Tellimust jälgitakse kolme oleku abil: tellimuse väli status, selle tootmisolek fulfillment_status ja iga saadetise väli status loendis shipments. Iga muudatus saadetakse veebihookis order.updated ja selle tagastab GET /orders/{order_id}.

Tellimuse olekud

Tellimuse välja status väärtused selles järjekorras, milles need saabuvad:

• imported - tellimus on API kaudu vastu võetud. Iga tellimus algab siit.
• on hold - saldo ei kata tellimuse maksumust. Kui saldot on täiendatud, naaseb tellimus olekusse imported ja jätkub.
• accepted - tellimus on vastu võetud ja saadetakse tootmisse.
• completed (lõplik) - kõik tooted on valmistatud.
• canceled (lõplik) - tellimus on tühistatud. See on võimalik seni, kuni tellimus on olekus imported, accepted või on hold ja tootmine pole veel alanud.

Täitmise olekud

Tellimuse ja iga tellimuserea välja fulfillment_status väärtused selles järjekorras, milles need saabuvad. Olek liigub ainult edasi, mitte kunagi tagasi:

• unfulfilled - tootmine pole alanud.
• scheduled - tellimus on planeeritud tootmispartiisse. Sellest hetkest alates ei saa seda enam tühistada.
• processing - tootmine käib.
• partially fulfilled - osa tooteid on valmis, ülejäänud on veel tootmises.
• fulfilled (lõplik) - kõik tooted on valmis. Tellimuse status muutub siis väärtuseks completed.

Tellimust tervikuna ei lükata kunagi tagasi. Üksiku toote võib tootmise ajal kvaliteedikontrollis tagasi lükata. Siis trükitakse see uuesti: see naaseb olekusse unfulfilled ja läbib tootmise veel kord, samal ajal kui tellimus säilitab oma oleku ja jätkub, kui toode on valmis.

Saadetise olekud

Iga saadetise välja status väärtused loendis shipments selles järjekorras, milles need saabuvad:

• pending - saadetist valmistatakse ette.
• registered - silt on vedaja juures loodud.
• collected - vedaja on paki peale võtnud.
• in transit - pakk on teel.
• delivered (lõplik) - pakk on kohale toimetatud.

Erandid:

• failed - vedaja teatas probleemist.
• returned (lõplik) - pakk on meile tagastatud.
• canceled (lõplik) - saadetis on tühistatud.

Konkreetse tellimuse täitmise oleku saamiseks saada GET-päring aadressile https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Vastus annab tellimusega seotud täitmiste loendi koos iga üksuse olekuga, tooteandmetega ja tootmisetappide edenemisega.

Vastuse näidis

{
    "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
                    }
                }
            ]
        }
    ]
}

Vastus sisaldab täitmiste loendit, kus iga kirje annab:

Iga täitmiskirje vastab tellimuse konkreetsele tootele või toote variandile ning igal tellimuses oleval tooteeksemplaril on oma täitmiskirje - iga üksust jälgitakse kogu tootmise vältel eraldi.

Kui tellimuse kohta täitmisi ei tagastata, ei ole tellimus veel töötlemisetappi jõudnud.

Kui lisad tellimusele lähtefaile, veendu, et need vastaksid järgmistele nõuetele:

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

PDF-i nõuded ja lehekülgede järjekord

Lehekülgede järjekord PDF-is on oluline. Leheküljed seotakse tootekihtidega asukoha järgi ja oodatav lehekülgede järjekord sõltub tootetüübist. Veendu, et sinu PDF-i leheküljed järgiksid esitatava toote õiget kihijärjestust.

Oluline: iga PDF-lehekülg peab vastama oma tootekihi nõutud mõõtmetele ja olema õigesti suunatud. Paiguta kujundus nii, et selle ülaosa jääks lehekülje ülaossa. Vale leheküljesuurus või -suund võib tootmises põhjustada mastaapimise, pööramise või joondamise probleeme.

Saage enne tellimuse esitamist teada, kui palju selle tarne maksab ja kui kaua see teel on, samade reeglite järgi, millega Fabrixa arvutab tellimuse enda hinna.

Et teada saada, millistesse riikidesse saab toote varianti tarnida, saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/shipping/countries oma tunnustega. Loend sisaldab nime järgi sorteeritud riike, kuhu variandi tootval asukohal on tarnetariif mõne sellise saatmispaki jaoks, millesse varianti saab pakkida. Riigil, mida loendis ei ole, puudub variandi jaoks tarnetariif.

Päringu parameetrid

Päringu näidis

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'

Vastuse näidis

{
    "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
        }
    ]
}

Vastuse väljad

Et teada saada, kui palju maksaks toote variandi tarne ja kui kaua see teel oleks, saatke GET-päring aadressile https://api.fabrixa.com/v2/integration/shipping/estimate oma tunnustega. Hinnang järgib samu reegleid, mille järgi tellimust hinnastatakse: ühikud pakitakse variandi tootva asukoha saatmispakkidesse ja iga paki hind arvutatakse marsruudi järgi sellest asukohast sihtriiki. Midagi ei tellita ega reserveerita ning tellimuse hind arvutatakse selle esitamisel, seega võib selle tarnehind erineda, kui tarnetariifid vahepeal muutuvad.

Päringu parameetrid

Päringu näidis

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'

Vastuse näidis

{
    "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
    }
}

Vastuse väljad

Päringule, mis valideerimist ei läbi, vastatakse koodiga 400 Bad Request ja iga välja põhjusega, samade sõnumitega nagu tellimuse rea puhul, näiteks The variant not found. Kui ükski saatmispakk ei mahuta ühikuid, on vastus 400 Bad Request sõnumiga No shipping package can carry the variant.

Fabrixa Studio on tööriist, mis laseb kasutajatel tooteid reaalajas sujuvalt kohandada ja isikupärastada intuitiivses liideses, kus nad saavad oma kujundusi luua või üles laadida.

Fabrixa Studio sobib ideaalselt ettevõtetele, kes pakuvad eritellimustooteid - kliendid näevad oma kujundust juba enne tellimuse vormistamist.

Fabrixa Studio saad oma veebisaidile manustada iframe-i abil. Nii saavad kliendid tooteid ostu ajal otse sinu saidil isikupärastada.

Fabrixa Studio manustamise iframe-i näidis:

<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>

Asenda väärtused product_sku, cart_item_key ja application_key oma dünaamiliste väärtustega.

• application_key - unikaalne võti Integration API-s autentimiseks.
• product_sku - toote variandi SKU, mis on saadud Integration API-st.
• cart_item_key - manustavalt platvormilt pärit unikaalne väärtus, mis tuvastab tootega seotud ostukorvi üksuse. Seda kasutatakse kasutaja kohanduste salvestamiseks; tellimuse loomisel tuvastab see salvestatud kohandused ja seob need tellimusega. Vaata näidet allpool.
• locale (valikuline) - Studio liidese ja veateadete keel, nt de_DE või de. Ilma selleta avaneb Studio ostja brauseri keeles, kui see on toetatud, muidu inglise keeles.

Studio päises on toote nimi nii, nagu see on sinu poes - sama pealkiri, mida näevad sinu kliendid -, ja selle all valitud variandi valikud. See on toote koopia sinu poes, nii et Fabrixas muudetud nimi kuvatakse ka Studios; locale seda ei tõlgi.

Päring tellimuse loomiseks väljaga 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": {
    "...": "..."
  }
}

Kui iframe-i sees klõpsatakse nuppu Lisa ostukorvi, käivitatakse järgmine käsk:

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

Sarnaselt siis, kui klõpsatakse nuppu Tagasi:

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

Meetod postMessage võimaldab iframe-i ja selle vanemakna vahelist eri päritolu suhtlust, nii saab see vanemakent konkreetsetest kasutaja tegevustest teavitada.

Meetodi postMessage esimene argument on andmed, mida soovid saata. Sõne 'customizationFinished' tähendab, et kasutaja on kohandamise lõpetanud ja lisab toote ostukorvi. 'closeButtonClicked' tähendab, et kasutaja valis tagasi mineku.

Vanemaknas kuula neid sõnumeid message-sündmuse kuulajaga:

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.');
        }
    }
});

Kontrolli alati sissetulevate sõnumite origin-i, et need tuleksid usaldusväärsest allikast. Sõltuvalt saadud sõnumist tee vajalikud toimingud - uuenda kasutajaliidest, töötle ostukorvi ja nii edasi. origin-i valideerimine on turvalisuse jaoks hädavajalik - see takistab volitamata skriptidel sinu rakendusega suhelda.

Kui kohandamine on lõpetatud, kuva lõplik kujundus allpool oleva eelvaate URL-iga. See URL tagastab kohandatud toote pildi, mis sobib src-väärtuseks <img>-sildis. Ideaalne kohandatud toote näitamiseks ostukorvis, tellimuse kokkuvõttes või mujal sinu poe liideses.

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

Asenda {CART_ITEM_KEY} tegeliku ostukorvi üksuse võtmega ja {APPLICATION_KEY} oma kehtiva rakenduse võtmega.

Kasutusnäidis pildisildis:

<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 kasutab veebihooke, et teavitada sinu süsteemi reaalajas toimuvatest sündmustest - tellimuste uuendustest või loomisest. Kui sündmus toimub, saadab Fabrixa sinu serverisse veebihooki koos asjakohase teabega. Sinu server peab avama avaliku POST-lõpp-punkti, mis sissetulevaid veebihooke käsitleb.

Veebihooki päring sisaldab järgmisi päiseid, mis aitavad sul sissetuleva päringu tuvastada ja kontrollida:

{
  "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"
}

Päiste ülevaade

• content-type - veebihookide puhul alati application/json.
• x-webhook-signature - HMAC-SHA256 allkiri päringu kontrollimiseks.
• x-webhook-topic - veebihooki sündmuse tüüp või teema. Näiteks:
  • order.created - käivitub uue tellimuse loomisel.
  • order.updated - käivitub olemasoleva tellimuse uuendamisel.

Webhookid saadetakse User-Agendiga Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); kui teie endpoint filtreerib automaatset liiklust, lubage see. Et olla kindel, et päring tuleb Fabrixalt, kontrollige x-webhook-signature.

Fabrixa veebihookid teavitavad sinu süsteemi tellimuse oleku või tegevuse muutustest. Iga veebihooki käivitab kindel x-webhook-topic väärtus. Praegu toetatud teemad:

Näidis andmetest, mis veebihookiga saadetakse. Need andmed kajastavad tellimuse uuendust:

{
  "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"
    }
  ]
}

Kui tellimus on teele saadetud, loetleb shipments iga saadetise koos vedaja (carrier), tarneviisi (method), oleku (status: pending, registered, collected, in transit, delivered, failed, returned või canceled) ja jälgimisega: tracking_number ja tracking_url, ning sama iga paki kohta väljal packages, kui saadetises on mitu pakki. Iga kord, kui saadetise olek või jälgimine muutub, saadetakse order.updated webhook ja GET /orders/{order_id} tagastab sama välja.

Et veenduda, et veebihooki päring on autentne ja muutmata, kontrolli päist x-webhook-signature. Selleks arvuta HMAC-SHA256 allkiri päringu töötlemata andmete ja oma salajase võtme põhjal uuesti ning võrdle seda saadud allkirjaga.

Puhta PHP näide

$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');
}

Laraveli näide

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...
}

Asenda $yourSecret oma jagatud salajase võtmega. Kasuta allkirjade võrdlemiseks alati hash_equals, et vähendada ajastusrünnakute ohtu.

Veebihookid lülitatakse vaikimisi välja pärast 10 ebaõnnestunud edastuskatset. Kui sinu lõpp-punkt tagastab ebaõnnestumise oleku, näiteks 404 või mis tahes 5xx vea, korratakse veebihooki kokku 10 korda. Kui see tagastab jätkuvalt vastusekoodi, mis ei ole 2xx ega 3xx, lülitatakse see välja. Õnnestunud vastused on:

• 2xx - näitab edukat töötlemist, nt 200 OK.
• 301 ja 302 - ümbersuunamisvastused, mis näitavad, et veebihook on edukalt käsitletud või edasi suunatud.

Soovitame tungivalt, et sinu lõpp-punkt tagastaks veebihooki kättesaamise kinnitamiseks olekukoodi 200 OK võimalikult kiiresti. Kuigi õnnestunuks loetakse iga 2xx või 3xx vastus, on 200 kõige levinum ja usaldusväärsem.

Edastuse ajalõpu või kordamise vältimiseks tagasta kohe 200 OK ja töötle veebihooki andmeid asünkroonselt, näiteks taustatöö või järjekorra kaudu. Kui sinu lõpp-punkti vastus võtab liiga kaua aega, võib seda lugeda ebaõnnestumiseks, isegi kui vastus lõpuks õnnestub.

Vastused olekukoodidega vahemikus 4xx või 5xx ning ajalõpud käivitavad kordused vastavalt kordamismehhanismile.