Fabrixa Integration API dokumentáció

Az Integration API eléréséhez hitelesítse a kéréseit egy alkalmazás hozzáférési tokennel és egy alkalmazáskulccsal is:

Authorization fejléc

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Alkalmazáskulcs fejléc

X-Application-Key: APPLICATION_KEY

Példa cURL parancsra

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'

Cserélje az APPLICATION_ACCESS_TOKEN értéket a saját hozzáférési tokenjére, az APPLICATION_KEY értéket pedig a saját alkalmazáskulcsára.

Az Integration API végpontjai erőforrástípus szerint szerveződnek, és a REST architekturális stílust követik. Minden végpont egy erőforrást képvisel, és az erőforrásokon végzett műveletek a szokásos HTTP-metódusokkal történnek.

Az Integration API minden kérése és válasza JSON formátumú, így egységes és könnyen használható felületet nyújt az API-val való munkához.

Az egyes végpontok részletes leírását, kérés- és válaszpéldákkal együtt, a Swagger dokumentációnkban találja.

Válaszformátum

Minden végpont egységes formátumban ad vissza adatokat, a következő objektumokkal:

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

A válaszobjektumok leírása

Minden API-kérés HTTP állapotkódot ad vissza, amely tájékoztat a válaszról.

A hibaválasz törzse

Példa egy hibaválasz törzsére:

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

Az errors részletezi, mi hiúsult meg. A messages tömb a hibaleírásokat sorolja fel. Bad Request esetén megkapja azoknak a mezőknek a nevét, amelyek nem mentek át a validáción.

Az Integration API alkalmazásonként 30 kérés/perc korlátot támogat.

Ha túllépi ezt a korlátot, 429 Too Many Requests választ kap.

Az Integration API minden válasza tartalmazza az X-RateLimit-Remaining fejlécet, vagyis hogy a kliens még hány kérést tehet, és az X-RateLimit-Limit fejlécet, azaz a percenként engedélyezett teljes mennyiséget.

A sandbox mód lehetővé teszi, hogy az integrációt az elejétől a végéig kipróbálja, mielőtt bármelyik valódi rendelést legyártanák vagy elszámolnák. A teljes fiókjára érvényes: az összes értékesítési csatorna – köztük az Integration API és a csatlakoztatott Shopify- és WooCommerce-áruházak – rendelései nem kerülnek gyártásra, és nem terhelik az egyenlegét. A fiókja addig van sandbox módban, amíg az állapota aktiválásra vár.

Sandbox módban:

• csatlakoztathatja Shopify- vagy WooCommerce-áruházát, illetve létrehozhat Integration API-csatornát;
• termékeket adhat hozzá, és ellenőrizheti az árakat és a szállítási becsléseket;
• rendeléseket importálhat, létrehozhat, módosíthat és lemondhat;
• meggyőződhet róla, hogy ezek közül egyik rendelést sem gyártják le, és egyik sem terheli az egyenlegét;
• ellenőrizheti a webhookok kézbesítését és az aláírásokat.

A rendelések teszteléséhez adjon hozzá termékeket a Fabrixa katalógusból: nyisson meg egy terméket, kattintson az Értékesítés gombra, és válasszon változatokat és terveket. Ezután megjelennek a Termékeim alatt.

Ha át szeretné állítani a fiókját sandbox módra, nyissa meg a Platformot, lépjen a Beállítások → Cég → Sandbox mód oldalra, és kattintson a Sandbox módba kapcsolás gombra. Bekapcsolhatja új értékesítési csatorna – köztük Integration API-csatorna – hozzáadásakor is, vagy írhat a support@fabrixa.com címre, és mi átállítjuk a fiókját. A sandbox mód csak aktív fiókokhoz érhető el.

Ha készen áll, aktiválja a fiókját a Platformban a Beállítások → Cég → Sandbox mód oldalon. Írhat a support@fabrixa.com címre is, és mi aktiváljuk Ön helyett. A csatlakoztatott áruházak és az API hitelesítő adatok tovább működnek, így semmit nem kell újra beállítani.

Az aktiválás után az összes új rendelés gyártásba kerül, és terheli az egyenlegét. Az aktiválás előtt létrehozott rendelések tesztrendelések maradnak: soha nem kerülnek legyártásra és elszámolásra, az aktiválás után sem.

A katalógus minden, amit a Fabrixa gyárt. Az Ön termékei azok a katalógustermékek, amelyeket a Fabrixa-fiókjához adott, saját nevekkel, leírásokkal, képekkel és SKU-kkal. Egy rendelési sor egy termékváltozatra hivatkozik - a termék egy méretére vagy kivitelére - annak sku vagy variant_id értékével: az Ön egyik termékének változatára, vagy egy közvetlenül rendelt katalógusváltozatra.

A Fabrixa által gyártott termékek listázásához küldjön GET kérést a https://api.fabrixa.com/v2/integration/catalog/products címre a hitelesítő adataival. Azokat az aktív termékeket sorolja fel, amelyeknek van olyan változata, amelyet egy nyomdai partner jelenleg gyárt, és csak ezeket a változatokat, mindegyiket a SKU-jával, eladási árával, méreteivel és opcióértékeivel.

Lekérdezési paraméterek

Példakérés

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'

Példaválasz

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

A válasz mezői

A katalógus kategóriáinak listázásához küldjön GET kérést a https://api.fabrixa.com/v2/integration/catalog/categories címre a hitelesítő adataival. A válasz a felső szintű kategóriákat tartalmazza, mindegyiket az alkategóriáival a sub_categories mezőben és a benne lévő katalógustermékek számával a products_count mezőben. A katalógus böngészésekor adja át egy kategória id értékét category_id-ként, vagy egy felső szintű kategória id értékét parent_category_id-ként, hogy egyszerre megkapja az összes alkategóriájának termékeit.

Lekérdezési paraméterek

Példakérés

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'

Példaválasz

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

A fiókjában lévő termékek listázásához küldjön GET kérést a https://api.fabrixa.com/v2/integration/products címre a hitelesítő adataival. Az Ön termékei azok a katalógustermékek, amelyeket a Fabrixa-fiókjához adott: azokat a neveket, leírásokat és képeket viselik, amelyeket ott adott nekik, a változataik pedig az Ön által választott SKU értékeket. Csak az aktív termékek szerepelnek, laponként tíz, hacsak nem ad meg limit értéket.

Lekérdezési paraméterek

Példakérés

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'

Példaválasz

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

Egyetlen termék olvasásához küldjön GET kérést a https://api.fabrixa.com/v2/integration/products/{product_id} címre, ahol a {product_id} a termék id értéke. A válasz ugyanazokat a mezőket tartalmazza, mint a lista. Az a termék, amely nincs az Ön fiókjában, még ha katalógustermék is, 404 Not Found választ ad a Product not found. üzenettel.

A válasz mezői

A változat a termék egy rendelhető kivitele - egy méret, egy szín -, és erre hivatkozik a rendelési sor a sku vagy a variant_id értékkel. Az egyik termékének változatát a https://api.fabrixa.com/v2/integration/variants/{variant_id} címre küldött GET kéréssel olvashatja, ahol a {variant_id} a változat id értéke. Az Ön fiókjában nem szereplő termék változata 404 Not Found választ ad a Variant not found. üzenettel.

Példakérés

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'

Példaválasz

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

A válasz mezői

Egy rendelési sor ehhez a változathoz, egy PDF-fel, amelynek oldalai a rétegei:

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

Mely változatok rendelhetők

Hozzon létre megrendeléseket a Fabrixában a saját webáruházából vagy platformjáról, csatolja a szükséges nyomtatási fájlokat, és kövesse minden tételt, ahogy végighalad a teljesítésen.

Ha a Fabrixa Integration API-n keresztül szeretne megrendelést létrehozni, küldjön POST kérést a https://api.fabrixa.com/v2/integration/orders címre. A kérés törzsének tartalmaznia kell:

A kérés törzsének felépítése

Példakérés

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

Példaválasz

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

Megrendelés módosításához küldjön PATCH kérést a https://api.fabrixa.com/v2/integration/orders/{order_id} címre, ahol a {order_id} a megrendelés Fabrixa-azonosítója. Csak az elküldött mezők változnak, a megrendelés állapota változatlan marad. A válasz a módosított megrendelést tartalmazza. Módosíthatja:

Példakérés

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

Példaválasz

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

Megrendelés lemondásához küldjön törzs nélküli POST kérést a https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel címre, ahol a {order_id} a megrendelés Fabrixa-azonosítója (a megrendelés numerikus id mezője), nem pedig az Ön rendelésszáma. A válasz a megrendelést canceled állapottal tartalmazza, és egy order.updated webhook is kiküldésre kerül.

Példaválasz

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

Ha a megrendelés nem mondható le, az API 412 Precondition Failed válasszal és az okot megadó üzenettel felel: a jelenlegi állapota nem teszi lehetővé (az állapot szerepel az üzenetben), vagy a gyártás már megkezdődött.

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

Egy megrendelést három állapot követ: a megrendelés status mezője, a gyártási állapota (fulfillment_status) és a shipments minden szállítmányának status mezője. Minden változást elküldünk az order.updated webhookban, és a GET /orders/{order_id} is visszaadja.

Megrendelési állapotok

A megrendelés status mezőjének értékei, abban a sorrendben, ahogyan bekövetkeznek:

• imported - a megrendelés beérkezett az API-n keresztül. Minden megrendelés itt kezdődik.
• on hold - az egyenleg nem fedezi a megrendelés költségét. Feltöltés után a megrendelés visszakerül imported állapotba, és folytatódik.
• accepted - a megrendelést elfogadtuk, és gyártásba kerül.
• completed (végleges) - minden tétel elkészült.
• canceled (végleges) - a megrendelést törölték. Ez addig lehetséges, amíg imported, accepted vagy on hold állapotban van, és a gyártás még nem kezdődött el.

Teljesítési állapotok

A megrendelés és minden megrendelési sor fulfillment_status mezőjének értékei, abban a sorrendben, ahogyan bekövetkeznek. Csak előre halad, soha nem vissza:

• unfulfilled - a gyártás még nem kezdődött el.
• scheduled - a megrendelés be van ütemezve egy gyártási tételbe. Ettől kezdve már nem törölhető.
• processing - a gyártás folyamatban van.
• partially fulfilled - néhány tétel elkészült, a többi még gyártás alatt áll.
• fulfilled (végleges) - minden tétel elkészült. A megrendelés status mezője ekkor completed lesz.

Egy megrendelést egészében soha nem utasítanak el. Egy-egy tételt a gyártás közbeni minőségellenőrzés során elutasíthatnak. Ekkor újranyomtatják: visszakerül unfulfilled állapotba, és még egyszer végigmegy a gyártáson, a megrendelés pedig megtartja az állapotát, és folytatódik, amint a tétel elkészül.

Szállítási állapotok

A shipments minden szállítmánya status mezőjének értékei, abban a sorrendben, ahogyan bekövetkeznek:

• pending - a szállítmány előkészítés alatt áll.
• registered - a címke elkészült a futárszolgálatnál.
• collected - a futárszolgálat átvette a csomagot.
• in transit - a csomag úton van.
• delivered (végleges) - a csomagot kézbesítették.

Kivételek:

• failed - a futárszolgálat problémát jelzett.
• returned (végleges) - a csomagot visszaküldték nekünk.
• canceled (végleges) - a szállítmányt törölték.

Egy adott megrendelés teljesítési állapotáért küldjön GET kérést a https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments címre. A válasz felsorolja a megrendeléshez tartozó teljesítéseket, köztük az egyes tételek állapotát, a termékadatokat és a gyártási lépések előrehaladását.

Példaválasz

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

A válasz teljesítések listáját tartalmazza, amelyek mindegyike megadja:

Minden teljesítési rekord a megrendelés egy adott termékéhez vagy termékváltozatához tartozik, és a megrendelésben szereplő minden példánynak külön teljesítési rekordja van - minden tételt egyedileg követünk a gyártás során.

Ha egy megrendeléshez nem érkezik vissza teljesítés, a megrendelés még nem került feldolgozási szakaszba.

Ha forrásfájlokat csatol a megrendeléshez, ügyeljen rá, hogy megfeleljenek a következő követelményeknek:

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

PDF-követelmények és oldalsorrend

A PDF-ben az oldalak sorrendje fontos. Az oldalakat pozíció szerint feleltetjük meg a termékrétegeknek, és az elvárt oldalsorrend a terméktípustól függ. Ügyeljen rá, hogy a PDF oldalai a beadott termékhez tartozó helyes rétegsorrendet kövessék.

Fontos: minden PDF-oldalnak meg kell felelnie a saját termékrétegéhez tartozó méreteknek, és helyes tájolásúnak kell lennie. Úgy helyezze el a grafikát, hogy a dizájn teteje az oldal tetejéhez illeszkedjen. A hibás oldalméret vagy tájolás méretezési, elforgatási vagy illesztési problémákat okozhat a gyártásban.

Tudja meg a megrendelés leadása előtt, mennyibe kerül a szállítása és mennyi ideig lesz úton, ugyanazon szabályok szerint, amelyekkel a Fabrixa magát a megrendelést árazza.

Ha meg szeretné tudni, mely országokba szállítható egy termékváltozat, küldjön GET kérést a https://api.fabrixa.com/v2/integration/shipping/countries címre a hitelesítő adataival. A lista név szerint rendezve tartalmazza azokat az országokat, amelyekbe a változatot gyártó telephelynek van szállítási díjszabása olyan szállítási csomagra, amelybe a változat becsomagolható. Ha egy ország nem szerepel a listán, oda nincs szállítási díjszabás a változathoz.

Lekérdezési paraméterek

Példakérés

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'

Példaválasz

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

A válasz mezői

Ha meg szeretné tudni, mennyibe kerülne egy termékváltozat szállítása és mennyi ideig lenne úton, küldjön GET kérést a https://api.fabrixa.com/v2/integration/shipping/estimate címre a hitelesítő adataival. A becslés ugyanazokat a szabályokat követi, amelyek szerint egy megrendelés ára kialakul: az egységeket a rendszer a változatot gyártó telephely szállítási csomagjaiba csomagolja, és minden csomag árát a telephelyről a célországba vezető útvonal alapján számítja ki. A rendszer semmit nem rendel meg és nem foglal le, a megrendelés árát pedig a leadásakor számítja ki, így annak szállítási díja eltérhet, ha a díjszabás időközben megváltozik.

Lekérdezési paraméterek

Példakérés

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'

Példaválasz

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

A válasz mezői

A validáción fennakadó kérésre az API 400 Bad Request válasszal és mezőnként az okkal felel, ugyanazokkal az üzenetekkel, mint egy rendelési sornál, például The variant not found. Ha egyetlen szállítási csomagba sem férnek bele az egységek, a válasz 400 Bad Request a No shipping package can carry the variant. üzenettel.

A Fabrixa Studio olyan eszköz, amellyel a felhasználók valós időben, gördülékenyen szabhatják testre és személyesíthetik a termékeket egy intuitív felületen, ahol saját dizájnt hozhatnak létre vagy tölthetnek fel.

A Fabrixa Studio ideális az egyedi termékeket kínáló vállalkozásoknak - a vásárlók már a megrendelés véglegesítése előtt láthatják a dizájnjukat.

A Fabrixa Studio iframe segítségével beágyazható a webhelyére. Így a vásárlói a fizetési folyamat során közvetlenül az Ön oldalán személyesíthetik a termékeket.

Példa iframe a Fabrixa Studio beágyazásához:

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

Cserélje a product_sku, cart_item_key és application_key értékeket a saját dinamikus értékeire.

• application_key - egyedi kulcs az Integration API-hoz való hitelesítéshez.
• product_sku - a termékváltozat SKU-ja, az Integration API-ból lekérve.
• cart_item_key - a beágyazó platformról származó egyedi érték, amely a termékhez tartozó kosártételt azonosítja. A felhasználói testreszabások mentésére szolgál; a megrendelés létrehozásakor azonosítja a mentett testreszabásokat, és a megrendeléshez rendeli őket. Lásd az alábbi példát.
• locale (opcionális) - a Studio felületének és hibaüzeneteinek nyelve, pl. de_DE vagy de. Nélküle a Studio a vásárló böngészőjének nyelvén nyílik meg, ha az támogatott, egyébként angolul.

A Studio fejléce a termék nevét úgy mutatja, ahogy az az Ön boltjában szerepel - ugyanazt a címet, amelyet a vásárlói látnak -, alatta a kiválasztott változat opcióival. Ez a termék saját másolata az Ön boltjában, így a Fabrixában módosított név a Studióban is megjelenik; a locale nem fordítja le.

Megrendelés létrehozása cart_item_key értékkel

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

Amikor az iframe-en belül a Kosárba gombra kattintanak, a következő utasítás fut le:

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

Hasonlóképpen, amikor a Vissza gombra kattintanak:

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

A postMessage metódus teszi lehetővé az iframe és a szülőablak közötti, eltérő eredetű kommunikációt, így az értesítheti a szülőablakot bizonyos felhasználói műveletekről.

A postMessage első paramétere a küldeni kívánt adat. A 'customizationFinished' szöveg azt jelzi, hogy a felhasználó véglegesítette a testreszabást, és a kosárba teszi a terméket. A 'closeButtonClicked' azt jelzi, hogy a felhasználó a visszalépést választotta.

A szülőablakban a message eseményfigyelővel hallgassa ezeket az üzeneteket:

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

Mindig ellenőrizze a bejövő üzenetek origin értékét, hogy megbízható forrásból származnak-e. A kapott üzenettől függően hajtsa végre a szükséges műveleteket - a felület frissítését, a kosár feldolgozását és így tovább. Az origin validálása biztonsági szempontból létfontosságú - megakadályozza, hogy illetéktelen szkriptek kommunikáljanak az alkalmazásával.

A testreszabás befejezése után az alábbi előnézeti URL-lel jelenítse meg a végleges dizájnt. Ez az URL a testreszabott termék képét adja vissza, amely src értékként használható egy <img> elemben. Ideális a testreszabott termék megjelenítéséhez a kosárban, a megrendelés összegzésében vagy bárhol az üzlete felületén.

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

Cserélje a {CART_ITEM_KEY} értéket a tényleges kosártétel-kulcsra, a {APPLICATION_KEY} értéket pedig az érvényes alkalmazáskulcsára.

Példa a használatra képelemben:

<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;" />

A Fabrixa webhookokkal értesíti a rendszerét a valós időben történő eseményekről - megrendelések frissítéséről vagy létrehozásáról. Amikor egy esemény bekövetkezik, a Fabrixa webhookot küld a szerverére a vonatkozó információkkal. A szerverének nyilvános POST végpontot kell biztosítania a bejövő webhookok kezeléséhez.

A webhook kérés a következő fejléceket tartalmazza, amelyek segítenek a bejövő kérés azonosításában és ellenőrzésében:

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

A fejlécek részletei

• content-type - webhookok esetén mindig application/json.
• x-webhook-signature - a kérés ellenőrzésére szolgáló HMAC-SHA256 aláírás.
• x-webhook-topic - a webhook eseménytípusa vagy témája. Például:
  • order.created - új megrendelés létrehozásakor indul.
  • order.updated - meglévő megrendelés frissítésekor indul.

A webhookokat a Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook) User-Agenttel küldjük; ha a végpontja szűri az automatizált forgalmat, engedélyezze. Ha biztos akar lenni abban, hogy egy kérés a Fabrixától jön, ellenőrizze az x-webhook-signature fejlécet.

A Fabrixa webhookjai értesítik a rendszerét a megrendelés állapotában vagy tevékenységében bekövetkező változásokról. Minden webhookot egy adott x-webhook-topic érték indít el. A jelenleg támogatott témák:

Példa a webhookkal küldött payloadra. Ez a payload egy megrendelés frissítését jelenti:

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

Amint a megrendelést feladták, a shipments felsorolja az egyes szállítmányokat a futárszolgálattal (carrier), a szállítási móddal (method), az állapottal (status: pending, registered, collected, in transit, delivered, failed, returned vagy canceled) és a nyomkövetéssel: tracking_number és tracking_url, valamint ugyanezt csomagonként a packages mezőben, ha egy szállítmány több csomagból áll. Egy szállítmány állapotának vagy nyomkövetésének minden változásakor egy order.updated webhook kerül kiküldésre, és a GET /orders/{order_id} ugyanezt a mezőt adja vissza.

Ahhoz, hogy megbizonyosodjon róla, hogy a webhook kérés eredeti és nem módosították, ellenőrizze az x-webhook-signature fejlécet. Ehhez a kérés nyers payloadja és a titkos kulcsa alapján újra ki kell számolnia a HMAC-SHA256 aláírást, majd össze kell hasonlítania a kapott aláírással.

Példa tiszta PHP-ban

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

Példa Laravelben

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

Cserélje a $yourSecret értéket a megosztott titkos kulcsára. Az aláírások összehasonlításához mindig a hash_equals függvényt használja, hogy csökkentse az időzítéses támadások esélyét.

A webhookok alapértelmezés szerint 10 sikertelen küldési kísérlet után letiltásra kerülnek. Ha a végpontja sikertelen állapotot ad vissza, például 404 vagy bármilyen 5xx hibát, a webhook összesen 10 alkalommal próbálkozik újra. Ha továbbra is 2xx vagy 3xx körön kívüli válaszkódot ad vissza, a webhook deaktiválódik. Sikeresnek számítanak:

• 2xx - sikeres feldolgozást jelez, például 200 OK.
• 301 és 302 - átirányítási válaszok, amelyek azt jelzik, hogy a webhookot sikeresen kezelték vagy továbbították.

Erősen javasoljuk, hogy a végpontja mielőbb 200 OK állapotkódot adjon vissza, visszaigazolva a webhook sikeres fogadását. Bár minden 2xx vagy 3xx válasz sikeresnek számít, a 200 a leggyakoribb és legmegbízhatóbb.

A küldési időtúllépések és újrapróbálkozások elkerüléséhez azonnal adjon vissza 200 OK választ, a webhook payloadját pedig aszinkron módon dolgozza fel, például háttérfeladattal vagy várólistával. Ha a végpontja túl sokáig válaszol, a kísérlet sikertelennek minősülhet, még akkor is, ha a válasz végül sikeres.

A 4xx vagy 5xx tartományba eső állapotkóddal érkező válaszok, valamint az időtúllépések az újrapróbálkozási mechanizmus szerint újabb kísérleteket indítanak.