Referenčna dokumentacija Fabrixa Integration API

Za dostop do Integration API morajo vse zahteve za preverjanje pristnosti vsebovati dostopni žeton aplikacije in ključ aplikacije:

Glava Authorization

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Glava s ključem aplikacije

X-Application-Key: APPLICATION_KEY

Primer ukaza cURL

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

Zamenjajte APPLICATION_ACCESS_TOKEN s svojim dejanskim dostopnim žetonom in APPLICATION_KEY s svojim dejanskim ključem aplikacije.

Končne točke Integration API so razvrščene po vrsti vira in sledijo arhitekturnemu slogu REST. Vsaka končna točka predstavlja vir, dejanja nad temi viri pa se izvajajo s standardnimi metodami HTTP.

Vse zahteve in odgovori Integration API so v obliki JSON, kar zagotavlja dosleden in enostaven vmesnik za delo z API-jem.

Vse podrobnosti o posameznih končnih točkah, vključno s primeri zahtev in odgovorov, najdete v naši dokumentaciji Swagger.

Oblika odgovora

Vse končne točke vračajo podatke v standardizirani obliki s temi objekti:

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

Opis objektov odgovora

Vse zahteve API vračajo statusne kode HTTP, ki povedo, kakšen je izid zahteve.

Telo odgovora z napako

Primer telesa odgovora z napako:

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

errors vsebuje podrobnosti o tem, kaj ni uspelo. Tabela messages navaja opise napak. Pri napaki Bad Request prejmete imena polj, ki niso prestala preverjanja veljavnosti.

Integration API omogoča največ 30 zahtev na aplikacijo na minuto.

Če to omejitev presežete, prejmete odgovor 429 Too Many Requests.

Vsi odgovori Integration API vsebujejo glavo X-RateLimit-Remaining, ki pove, koliko zahtev lahko odjemalec še pošlje, in glavo X-RateLimit-Limit, ki pove skupno dovoljeno število zahtev na minuto.

Način peskovnika vam omogoča, da integracijo preizkusite od začetka do konca, preden se katero koli pravo naročilo izdela ali obračuna. Velja za ves vaš račun: naročila iz vseh prodajnih kanalov, vključno z Integration API in povezanimi trgovinami Shopify in WooCommerce, se ne izdelujejo in se ne bremenijo z vašega stanja. Vaš račun je v načinu peskovnika, dokler ima stanje čaka na aktivacijo.

V načinu peskovnika lahko:

• povežete svojo trgovino Shopify ali WooCommerce ali ustvarite kanal Integration API;
• dodajate izdelke ter preverjate cene in ocene stroškov dostave;
• uvažate, ustvarjate, posodabljate in prekličete naročila;
• preverite, da se nobeno od teh naročil ne izdeluje in ne bremeni z vašega stanja;
• preverite dostavo webhookov in podpise.

Za preizkus naročil dodajte izdelke iz kataloga Fabrixa: odprite izdelek, kliknite Prodajaj to in izberite različice ter oblikovanja. Nato se prikažejo v razdelku Moji izdelki.

Če želite račun preklopiti v način peskovnika, odprite Platform, pojdite na Nastavitve → Podjetje → Način peskovnika in kliknite Preklopi v način peskovnika. Vklopite ga lahko tudi ob dodajanju novega prodajnega kanala, vključno s kanalom Integration API, ali pa nam pišite na support@fabrixa.com, mi pa bomo račun preklopili namesto vas. Način peskovnika je na voljo samo za aktivne račune.

Ko ste pripravljeni, račun aktivirajte sami v Platformu v razdelku Nastavitve → Podjetje → Način peskovnika. Lahko nam tudi pišete na support@fabrixa.com, mi pa ga bomo aktivirali namesto vas. Povezane trgovine in poverilnice API še naprej delujejo, zato vam ni treba ničesar znova nastavljati.

Po aktivaciji gredo vsa nova naročila v proizvodnjo in se bremenijo z vašega stanja. Naročila, ustvarjena pred aktivacijo, ostanejo testna: nikoli se ne izdelajo ali obračunajo, tudi po aktivaciji ne.

Katalog je vse, kar Fabrixa izdeluje. Vaši izdelki so izdelki iz kataloga, ki ste jih dodali v svoj račun Fabrixa, z lastnimi imeni, opisi, slikami in SKU-ji. Vrstica naročila se nanaša na različico izdelka - eno velikost ali izvedbo izdelka - prek njenega sku ali variant_id: na različico enega od vaših izdelkov ali na različico iz kataloga, naročeno neposredno.

Za seznam izdelkov, ki jih Fabrixa izdeluje, pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/catalog/products s svojimi poverilnicami. Vsebuje aktivne izdelke, ki imajo različico, ki jo tiskarski partner trenutno izdeluje, in samo te različice - vsako z njenim SKU, prodajno ceno, merami in vrednostmi možnosti.

Parametri poizvedbe

Primer zahteve

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'

Primer odgovora

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

Polja odgovora

Za seznam kategorij, v katere je katalog urejen, pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/catalog/categories s svojimi poverilnicami. Odgovor vsebuje kategorije najvišje ravni, vsako s podkategorijami, ugnezdenimi v sub_categories, in številom izdelkov kataloga v njej v products_count. Pri brskanju po katalogu posredujte id kategorije kot category_id ali id kategorije najvišje ravni kot parent_category_id, da naenkrat dobite izdelke vseh njenih podkategorij.

Parametri poizvedbe

Primer zahteve

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'

Primer odgovora

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

Za seznam izdelkov v svojem računu pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/products s svojimi poverilnicami. Vaši izdelki so izdelki iz kataloga, ki ste jih dodali v svoj račun Fabrixa: nosijo imena, opise in slike, ki ste jim jih tam dali, njihove različice pa vrednosti SKU, ki ste jih izbrali. Na seznamu so samo aktivni izdelki, deset na stran, razen če posredujete limit.

Parametri poizvedbe

Primer zahteve

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'

Primer odgovora

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

Za branje enega izdelka pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/products/{product_id}, kjer je {product_id} njegov id. Odgovor vsebuje ista polja kot seznam. Izdelek, ki ni v vašem računu, tudi izdelek iz kataloga, odgovori s 404 Not Found in sporočilom Product not found.

Polja odgovora

Različica je ena izvedba izdelka, ki jo je mogoče naročiti - ena velikost, ena barva - in nanjo se nanaša vrstica naročila prek sku ali variant_id. Za branje različice enega od svojih izdelkov pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/variants/{variant_id}, kjer je {variant_id} njen id. Različica izdelka, ki ni v vašem računu, odgovori s 404 Not Found in sporočilom Variant not found.

Primer zahteve

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'

Primer odgovora

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

Polja odgovora

Vrstica naročila za to različico s PDF-jem, katerega strani so njene plasti:

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

Katere različice je mogoče naročiti

Ustvarjajte naročila v sistemu Fabrixa iz svoje spletne trgovine ali platforme, priložite potrebne datoteke za tisk in spremljajte vsako postavko na njeni poti skozi izpolnitev.

Če želite ustvariti naročilo prek Fabrixa Integration API, pošljite zahtevo POST na https://api.fabrixa.com/v2/integration/orders. Telo zahteve mora vsebovati:

Struktura telesa zahteve

Primer zahteve

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

Primer odgovora

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

Če želite posodobiti naročilo, pošljite zahtevo PATCH na https://api.fabrixa.com/v2/integration/orders/{order_id}, kjer je {order_id} ID naročila v sistemu Fabrixa. Spremenijo se samo polja, ki jih pošljete, status naročila pa ostane nespremenjen. Odgovor vsebuje posodobljeno naročilo. Spremenite lahko:

Primer zahteve

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

Primer odgovora

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

Če želite preklicati naročilo, pošljite zahtevo POST brez telesa na https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, kjer je {order_id} ID naročila v sistemu Fabrixa (številsko polje id naročila), ne vaša številka naročila. Odgovor vsebuje naročilo s statusom canceled, poslan pa je tudi webhook order.updated.

Primer odgovora

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

Če naročila ni mogoče preklicati, API vrne odgovor 412 Precondition Failed s sporočilom, ki pojasni razlog: trenutni status naročila tega ne dovoljuje (status je naveden v sporočilu) ali pa se je proizvodnja že začela.

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

Naročilo se spremlja s tremi statusi: poljem status naročila, njegovim proizvodnim statusom fulfillment_status in poljem status vsake pošiljke v shipments. Vsaka sprememba se pošlje v webhooku order.updated in jo vrne GET /orders/{order_id}.

Statusi naročila

Vrednosti polja status naročila v vrstnem redu, v katerem nastopijo:

• imported - naročilo je bilo prejeto prek API-ja. Vsako naročilo se začne tukaj.
• on hold - stanje ne pokrije stroškov naročila. Ko je dopolnjeno, se naročilo vrne na imported in se nadaljuje.
• accepted - naročilo je bilo sprejeto in gre v proizvodnjo.
• completed (končen) - vsi izdelki so bili izdelani.
• canceled (končen) - naročilo je bilo preklicano. To je mogoče, dokler je v statusu imported, accepted ali on hold in se proizvodnja še ni začela.

Statusi izpolnitve

Vrednosti polja fulfillment_status naročila in vsake njegove postavke v vrstnem redu, v katerem nastopijo. Status se spreminja samo naprej, nikoli nazaj:

• unfulfilled - proizvodnja se še ni začela.
• scheduled - naročilo je načrtovano v proizvodni seriji. Od tega trenutka ga ni več mogoče preklicati.
• processing - proizvodnja poteka.
• partially fulfilled - nekateri izdelki so končani, ostali so še v proizvodnji.
• fulfilled (končen) - vsi izdelki so končani. Takrat status naročila postane completed.

Naročilo kot celota ni nikoli zavrnjeno. Posamezen izdelek je lahko zavrnjen pri kontroli kakovosti med proizvodnjo. Nato se natisne znova: vrne se na unfulfilled in še enkrat gre skozi proizvodnjo, naročilo pa ohrani svoj status in se nadaljuje, ko je izdelek končan.

Statusi pošiljke

Vrednosti polja status vsake pošiljke v shipments v vrstnem redu, v katerem nastopijo:

• pending - pošiljka se pripravlja.
• registered - nalepka je bila ustvarjena pri prevozniku.
• collected - prevoznik je prevzel paket.
• in transit - paket je na poti.
• delivered (končen) - paket je bil dostavljen.

Izjeme:

• failed - prevoznik je sporočil težavo.
• returned (končen) - paket nam je bil vrnjen.
• canceled (končen) - pošiljka je bila preklicana.

Če želite pridobiti status izpolnitve določenega naročila, pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Odgovor vsebuje seznam izpolnitev, povezanih z naročilom, vključno s statusom vsake postavke, podrobnostmi o izdelku in napredkom proizvodnih korakov.

Primer odgovora

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

Odgovor vsebuje seznam izpolnitev, pri čemer vsaka vsebuje:

Vsak zapis izpolnitve ustreza določenemu izdelku ali različici izdelka v naročilu, vsak kos izdelka v naročilu pa ima svoj zapis izpolnitve - vsaka postavka se med proizvodnjo spremlja posebej.

Če za naročilo ni vrnjena nobena izpolnitev, naročilo še ni vstopilo v fazo obdelave.

Če naročilu prilagate izvorne datoteke, poskrbite, da izpolnjujejo naslednje zahteve:

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

Zahteve za PDF in vrstni red strani

Vrstni red strani v datoteki PDF je pomemben. Strani se plastem izdelka dodelijo glede na položaj, pričakovani vrstni red strani pa je odvisen od vrste izdelka. Poskrbite, da strani v vaši datoteki PDF sledijo pravilnemu zaporedju plasti za izdelek, ki ga pošiljate.

Pomembno: vsaka stran PDF mora ustrezati zahtevanim dimenzijam za svojo plast izdelka in biti pravilno usmerjena. Grafiko postavite tako, da je vrh dizajna poravnan z vrhom strani. Nepravilna velikost ali usmerjenost strani lahko v proizvodnji povzroči težave s skaliranjem, zasukom ali poravnavo.

Preden oddate naročilo, ugotovite, koliko bo stala njegova dostava in koliko časa bo na poti, po enakih pravilih, po katerih Fabrixa izračuna samo naročilo.

Če želite izvedeti, v katere države je mogoče poslati različico izdelka, pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/shipping/countries s svojimi poverilnicami. Seznam vsebuje po imenu razvrščene države, v katere ima lokacija, kjer se različica izdeluje, tarifo za pošiljanje, in sicer za paket za pošiljanje, v katerega je mogoče zapakirati različico. Država, ki je ni na seznamu, za različico nima tarife za pošiljanje.

Parametri poizvedbe

Primer zahteve

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'

Primer odgovora

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

Polja odgovora

Če želite izvedeti, koliko bi stala dostava različice izdelka in kako dolgo bi trajala, pošljite zahtevo GET na https://api.fabrixa.com/v2/integration/shipping/estimate s svojimi poverilnicami. Ocena sledi pravilom, po katerih se izračuna cena naročila: enote se zapakirajo v pakete za pošiljanje lokacije, kjer se različica izdeluje, cena vsakega paketa pa se določi po relaciji od te lokacije do namembne države. Ničesar se ne naroči in ne rezervira, cena naročila pa se izračuna ob njegovi oddaji, zato se lahko stroški dostave razlikujejo, če se tarife vmes spremenijo.

Parametri poizvedbe

Primer zahteve

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'

Primer odgovora

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

Polja odgovora

Zahteva, ki ne prestane preverjanja veljavnosti, je zavrnjena s 400 Bad Request in razlogom za vsako polje, z enakimi sporočili kot pri vrstici naročila, na primer The variant not found. Kadar noben paket za pošiljanje ne more sprejeti enot, je odgovor 400 Bad Request s sporočilom No shipping package can carry the variant.

Fabrixa Studio je orodje, ki uporabnikom omogoča, da v realnem času preprosto prilagajajo in personalizirajo izdelke prek intuitivnega vmesnika, v katerem lahko ustvarijo ali naložijo lastne dizajne.

Fabrixa Studio je idealen za podjetja, ki ponujajo izdelke po meri - strankam omogoča, da si svoj dizajn ogledajo, preden zaključijo naročilo.

Fabrixa Studio lahko v svoje spletno mesto vdelate z elementom iframe. Tako lahko vaše stranke izdelke personalizirajo neposredno na vašem spletnem mestu med nakupom.

Primer elementa iframe za vdelavo orodja Fabrixa Studio:

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

Vrednosti za product_sku, cart_item_key in application_key zamenjajte s svojimi dinamičnimi vrednostmi.

• application_key - edinstven ključ za preverjanje pristnosti v Integration API.
• product_sku - SKU različice izdelka, pridobljen iz Integration API.
• cart_item_key - edinstvena vrednost s platforme, v katero je Studio vdelan, ki označuje postavko v košarici, povezano z izdelkom. Uporablja se za shranjevanje personalizacij uporabnika; pri ustvarjanju naročila prepozna shranjene personalizacije in jih dodeli naročilu. Glejte primer spodaj.
• locale (neobvezno) - jezik vmesnika Studia in njegovih sporočil o napakah, npr. de_DE ali de. Brez njega se Studio odpre v jeziku brskalnika kupca, če je podprt, sicer v angleščini.

Glava Studia prikazuje ime izdelka, kot je v vaši trgovini - isti naslov, ki ga vidijo vaše stranke - pod njim pa možnosti izbrane različice. To je lastna kopija izdelka v vaši trgovini, zato se ime, ki ga spremenite v Fabrixi, prikaže tudi v Studiu; locale ga ne prevede.

Zahteva za ustvarjanje naročila s ključem 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": {
    "...": "..."
  }
}

Ko uporabnik v elementu iframe klikne gumb Dodaj v košarico, se izvede naslednji ukaz:

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

Podobno ob kliku na gumb Nazaj:

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

Metoda postMessage omogoča komunikacijo med elementom iframe in njegovim nadrejenim oknom tudi med različnimi izvori (cross-origin), tako da lahko iframe nadrejeno okno obvesti o določenih dejanjih uporabnika.

Prvi argument metode postMessage so podatki, ki jih želite poslati. Niz 'customizationFinished' pomeni, da je uporabnik dokončal personalizacijo in dodaja izdelek v košarico. 'closeButtonClicked' pomeni, da se je uporabnik odločil vrniti nazaj.

V nadrejenem oknu ta sporočila prestrezite s poslušalcem dogodka message:

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

Vedno preverite origin dohodnih sporočil, da se prepričate, da prihajajo iz zaupanja vrednega vira. Glede na prejeto sporočilo izvedite potrebna dejanja - posodobite uporabniški vmesnik, obdelajte košarico ipd. Preverjanje origin je ključno za varnost - nepooblaščenim skriptom preprečuje interakcijo z vašo aplikacijo.

Ko je personalizacija dokončana, prikažite končni dizajn s spodnjim URL-jem predogleda. Ta URL vrne sliko personaliziranega izdelka, primerno za vrednost src v oznaki <img>. Idealen je za prikaz personaliziranega izdelka v košarici, povzetku naročila ali kjer koli drugje v vmesniku vaše trgovine.

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

Zamenjajte {CART_ITEM_KEY} z dejanskim ključem postavke v košarici in {APPLICATION_KEY} s svojim veljavnim ključem aplikacije.

Primer uporabe v oznaki slike:

<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 z webhooki obvešča vaš sistem o dogodkih v realnem času - o posodobitvah ali ustvarjanju naročil. Ko pride do dogodka, Fabrixa na vaš strežnik pošlje webhook z ustreznimi podatki. Vaš strežnik mora za sprejem dohodnih webhookov izpostaviti javno končno točko POST.

Zahteva webhooka vsebuje naslednje glave, s katerimi lahko dohodno zahtevo prepoznate in preverite:

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

Pregled glav

• content-type - pri webhookih vedno nastavljeno na application/json.
• x-webhook-signature - podpis HMAC-SHA256 za preverjanje zahteve.
• x-webhook-topic - vrsta dogodka oziroma tema webhooka. Na primer:
  • order.created - sproži se ob ustvarjanju novega naročila.
  • order.updated - sproži se ob posodobitvi obstoječega naročila.

Webhooki se pošiljajo z glavo User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); če vaša končna točka filtrira samodejni promet, ga dovolite. Da se prepričate, da zahteva res prihaja iz sistema Fabrixa, preverite x-webhook-signature.

Webhooki Fabrixa obveščajo vaš sistem o spremembah statusa naročila ali drugih dejavnostih. Vsak webhook sproži določena vrednost x-webhook-topic. Trenutno podprte teme:

Primer vsebine, poslane z webhookom. Ta vsebina predstavlja posodobitev naročila:

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

Ko je naročilo odposlano, shipments navaja vse pošiljke z njihovim prevoznikom (carrier), načinom pošiljanja (method), statusom (status: pending, registered, collected, in transit, delivered, failed, returned ali canceled) in podatki za sledenje: tracking_number in tracking_url, enako pa tudi za vsak paket v packages, kadar pošiljka obsega več paketov. Webhook order.updated se pošlje ob vsaki spremembi statusa ali podatkov za sledenje pošiljke, enako polje pa vrne tudi GET /orders/{order_id}.

Da zagotovite, da je zahteva webhooka pristna in nespremenjena, preverite glavo x-webhook-signature. To pomeni, da podpis HMAC-SHA256 ponovno izračunate iz neobdelane vsebine zahteve in svojega skrivnega ključa ter ga primerjate s prejetim podpisom.

Primer v čistem PHP

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

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

Primer v Laravelu

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

Zamenjajte $yourSecret s svojim skupnim skrivnim ključem. Za primerjavo podpisov vedno uporabljajte hash_equals, da zmanjšate tveganje časovnih napadov.

Webhooki se privzeto onemogočijo po 10 neuspešnih poskusih dostave. Če vaša končna točka vrne neuspešen status, na primer 404 ali katero koli napako 5xx, se dostava webhooka ponovi, skupno do 10-krat. Če končna točka še naprej vrača kodo, ki ni 2xx ali 3xx, se webhook deaktivira. Za uspešne odgovore veljajo:

• 2xx - pomeni uspešno obdelavo, npr. 200 OK.
• 301 in 302 - odgovori s preusmeritvijo, ki pomenijo, da je bil webhook uspešno obravnavan ali posredovan naprej.

Močno priporočamo, da vaša končna točka čim hitreje vrne statusno kodo 200 OK in s tem potrdi uspešen prejem webhooka. Čeprav se za uspešen šteje vsak odgovor 2xx ali 3xx, je 200 najpogosteje uporabljena in najzanesljivejša koda.

Da se izognete prekoračitvi časovne omejitve dostave ali ponovnim poskusom, takoj vrnite 200 OK, vsebino webhooka pa obdelajte asinhrono, na primer v opravilu v ozadju ali v čakalni vrsti. Če vaša končna točka za odgovor potrebuje predolgo, se lahko dostava šteje za neuspešno, tudi če je odgovor na koncu uspešen.

Odgovori s statusnimi kodami iz razponov 4xx ali 5xx ter prekoračitve časovne omejitve sprožijo ponovne poskuse v skladu z mehanizmom ponovnih poskusov.