Referentna dokumentacija za Fabrixa Integration API

Za pristup Integration API-ju autentificirajte svoje zahtjeve pomoću pristupnog tokena aplikacije i ključa aplikacije:

Zaglavlje Authorization

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Zaglavlje s ključem aplikacije

X-Application-Key: APPLICATION_KEY

Primjer naredbe 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'

Zamijenite APPLICATION_ACCESS_TOKEN svojim stvarnim pristupnim tokenom, a APPLICATION_KEY svojim stvarnim ključem aplikacije.

Endpointi Integration API-ja organizirani su prema vrsti resursa i slijede arhitekturni stil REST. Svaki endpoint predstavlja resurs, a radnje nad tim resursima izvode se standardnim HTTP metodama.

Svi zahtjevi i odgovori Integration API-ja u formatu su JSON, što osigurava dosljedno i jednostavno sučelje za rad s API-jem.

Potpune pojedinosti o svim endpointima, uključujući primjere zahtjeva i odgovora, potražite u našoj Swagger dokumentaciji.

Format odgovora

Svi endpointi vraćaju podatke u standardiziranom formatu sa sljedećim objektima:

{
  "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 objekata odgovora

Svi API zahtjevi vraćaju HTTP statusne kodove koji pružaju uvid u odgovor.

Tijelo odgovora s pogreškom

Primjer tijela odgovora s pogreškom:

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

errors sadrži pojedinosti o tome što nije uspjelo. Polje messages navodi opise pogrešaka. Kod pogreške Bad Request dobit ćete nazive polja koja nisu prošla validaciju.

Integration API podržava ograničenje od 30 zahtjeva po aplikaciji u minuti.

Ako premašite to ograničenje, dobit ćete odgovor 429 Too Many Requests.

Svi odgovori Integration API-ja sadrže zaglavlje X-RateLimit-Remaining, koje pokazuje koliko još zahtjeva klijent može poslati, i zaglavlje X-RateLimit-Limit, koje pokazuje ukupan dopušteni broj zahtjeva u minuti.

Sandbox način rada omogućuje vam testiranje integracije od početka do kraja prije nego što se ijedna stvarna narudžba proizvede ili naplati. Vrijedi za cijeli vaš račun: narudžbe iz svih prodajnih kanala, uključujući Integration API i povezane trgovine Shopify i WooCommerce, ne proizvode se i ne naplaćuju s vašeg stanja. Vaš je račun u sandbox načinu rada dok mu je status čeka aktivaciju.

U sandbox načinu rada možete:

• povezati svoju trgovinu Shopify ili WooCommerce ili izraditi kanal Integration API;
• dodavati proizvode te provjeravati cijene i procjene dostave;
• uvoziti, izrađivati, ažurirati i otkazivati narudžbe;
• provjeriti da se nijedna od tih narudžbi ne proizvodi niti naplaćuje s vašeg stanja;
• provjeriti isporuku webhookova i potpise.

Za testiranje narudžbi dodajte proizvode iz Fabrixa kataloga: otvorite proizvod, kliknite Prodaj ovo i odaberite varijante i dizajne. Zatim se pojavljuju u odjeljku Moji proizvodi.

Za prebacivanje računa u sandbox način rada otvorite Platform, idite na Postavke → Tvrtka → Sandbox način rada i kliknite Prebaci u sandbox način rada. Možete ga uključiti i prilikom dodavanja novog prodajnog kanala, uključujući kanal Integration API, ili nam pisati na support@fabrixa.com pa ćemo vaš račun prebaciti umjesto vas. Sandbox način rada dostupan je samo aktivnim računima.

Kad budete spremni, sami aktivirajte račun u Platformu u odjeljku Postavke → Tvrtka → Sandbox način rada. Možete nam i pisati na support@fabrixa.com pa ćemo ga aktivirati umjesto vas. Povezane trgovine i API vjerodajnice nastavljaju raditi, pa ništa ne treba ponovno konfigurirati.

Nakon aktivacije sve nove narudžbe idu u proizvodnju i naplaćuju se s vašeg stanja. Narudžbe izrađene prije aktivacije ostaju testne: nikada se ne proizvode niti naplaćuju, čak ni nakon aktivacije.

Katalog je sve što Fabrixa proizvodi. Vaši proizvodi su proizvodi iz kataloga koje ste dodali na svoj Fabrixa račun, s vlastitim nazivima, opisima, slikama i SKU-ovima. Stavka narudžbe odnosi se na varijantu proizvoda - jednu veličinu ili izvedbu proizvoda - putem njezina sku ili variant_id: na varijantu jednog od vaših proizvoda ili na varijantu iz kataloga naručenu izravno.

Da biste dobili popis proizvoda koje Fabrixa proizvodi, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/catalog/products sa svojim vjerodajnicama. Sadrži aktivne proizvode koji imaju varijantu koju tiskarski partner trenutačno proizvodi, i samo te varijante - svaku s njezinim SKU, prodajnom cijenom, dimenzijama i vrijednostima opcija.

Parametri upita

Primjer zahtjeva

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'

Primjer 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

Da biste dobili popis kategorija u koje je katalog uređen, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/catalog/categories sa svojim vjerodajnicama. Odgovor sadrži kategorije najviše razine, svaku s potkategorijama ugniježđenima u sub_categories i brojem proizvoda kataloga u njoj u products_count. Pri pregledu kataloga proslijedite id kategorije kao category_id, ili id kategorije najviše razine kao parent_category_id da biste odjednom dobili proizvode svih njezinih potkategorija.

Parametri upita

Primjer zahtjeva

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'

Primjer 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
                }
            ]
        }
    ]
}

Da biste dobili popis proizvoda na svojem računu, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/products sa svojim vjerodajnicama. Vaši proizvodi su proizvodi iz kataloga koje ste dodali na svoj Fabrixa račun: nose nazive, opise i slike koje ste im ondje dali, a njihove varijante vrijednosti SKU koje ste odabrali. Na popisu su samo aktivni proizvodi, deset po stranici ako ne proslijedite limit.

Parametri upita

Primjer zahtjeva

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'

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

Da biste pročitali jedan proizvod, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/products/{product_id}, gdje je {product_id} njegov id. Odgovor sadrži ista polja kao popis. Proizvod koji nije na vašem računu, pa ni proizvod iz kataloga, odgovara s 404 Not Found i porukom Product not found.

Polja odgovora

Varijanta je jedna izvedba proizvoda koja se može naručiti - jedna veličina, jedna boja - i na nju se odnosi stavka narudžbe putem sku ili variant_id. Da biste pročitali varijantu jednog od svojih proizvoda, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/variants/{variant_id}, gdje je {variant_id} njezin id. Varijanta proizvoda koji nije na vašem računu odgovara s 404 Not Found i porukom Variant not found.

Primjer zahtjeva

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'

Primjer 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

Stavka narudžbe za ovu varijantu, s PDF-om čije su stranice njezini slojevi:

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

Koje se varijante mogu naručiti

Kreirajte narudžbe u Fabrixi iz vlastite web-trgovine ili platforme, priložite potrebne datoteke za tisak i pratite svaku stavku dok prolazi kroz ispunjenje.

Da biste kreirali narudžbu putem Fabrixa Integration API-ja, pošaljite zahtjev POST na https://api.fabrixa.com/v2/integration/orders. Tijelo zahtjeva mora sadržavati:

Struktura tijela zahtjeva

Primjer zahtjeva

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

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

Da biste ažurirali narudžbu, pošaljite zahtjev PATCH na https://api.fabrixa.com/v2/integration/orders/{order_id}, pri čemu je {order_id} ID narudžbe u Fabrixi. Mijenjaju se samo polja koja pošaljete, a status narudžbe ostaje nepromijenjen. Odgovor sadrži ažuriranu narudžbu. Možete promijeniti:

Primjer zahtjeva

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

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

Da biste otkazali narudžbu, pošaljite zahtjev POST bez tijela na https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, pri čemu je {order_id} ID narudžbe u Fabrixi (numeričko polje id narudžbe), a ne vaš broj narudžbe. Odgovor sadrži narudžbu sa statusom canceled i šalje se webhook order.updated.

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

Ako se narudžba ne može otkazati, API odgovara s 412 Precondition Failed i porukom koja objašnjava razlog: njezin trenutačni status to ne dopušta (status je naveden u poruci) ili je proizvodnja već započ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)."
        ]
    }
}

Narudžba se prati pomoću tri statusa: polja status narudžbe, njezina proizvodnog statusa fulfillment_status i polja status svake pošiljke u shipments. Svaka promjena šalje se u webhooku order.updated i vraća je GET /orders/{order_id}.

Statusi narudžbe

Vrijednosti polja status narudžbe redoslijedom kojim nastupaju:

• imported - narudžba je zaprimljena putem API-ja. Svaka narudžba počinje ovdje.
• on hold - saldo ne pokriva trošak narudžbe. Nakon nadoplate narudžba se vraća na imported i nastavlja.
• accepted - narudžba je prihvaćena i šalje se u proizvodnju.
• completed (konačan) - svi artikli su proizvedeni.
• canceled (konačan) - narudžba je otkazana. To je moguće dok je u statusu imported, accepted ili on hold i proizvodnja još nije počela.

Statusi ispunjenja

Vrijednosti polja fulfillment_status narudžbe i svake njezine stavke redoslijedom kojim nastupaju. Status se mijenja samo naprijed, nikad unatrag:

• unfulfilled - proizvodnja još nije počela.
• scheduled - narudžba je planirana u proizvodnoj seriji. Od ovog trenutka više se ne može otkazati.
• processing - proizvodnja je u tijeku.
• partially fulfilled - neki su artikli gotovi, ostali su još u proizvodnji.
• fulfilled (konačan) - svi su artikli gotovi. Tada status narudžbe postaje completed.

Narudžba u cjelini nikada se ne odbija. Pojedini artikl može biti odbijen pri kontroli kvalitete tijekom proizvodnje. Tada se ponovno ispisuje: vraća se na unfulfilled i još jednom prolazi kroz proizvodnju, dok narudžba zadržava svoj status i nastavlja čim artikl bude gotov.

Statusi pošiljke

Vrijednosti polja status svake pošiljke u shipments redoslijedom kojim nastupaju:

• pending - pošiljka se priprema.
• registered - naljepnica je izrađena kod prijevoznika.
• collected - prijevoznik je preuzeo paket.
• in transit - paket je na putu.
• delivered (konačan) - paket je dostavljen.

Iznimke:

• failed - prijevoznik je prijavio problem.
• returned (konačan) - paket nam je vraćen.
• canceled (konačan) - pošiljka je otkazana.

Da biste dobili status ispunjenja određene narudžbe, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Odgovor sadrži popis ispunjenja povezanih s narudžbom, uključujući status svake stavke, pojedinosti o proizvodu i napredak proizvodnih koraka.

Primjer 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 sadrži popis ispunjenja, a svako od njih navodi:

Svaki zapis o ispunjenju odgovara određenom proizvodu ili varijanti proizvoda u narudžbi, a svaki primjerak proizvoda u narudžbi ima vlastiti zapis o ispunjenju - svaka se stavka tijekom proizvodnje prati zasebno.

Ako za narudžbu nisu vraćena nikakva ispunjenja, narudžba još nije ušla u fazu obrade.

Kada narudžbi prilažete izvorne datoteke, provjerite zadovoljavaju li sljedeće zahtjeve:

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

Zahtjevi za PDF i redoslijed stranica

Redoslijed stranica u PDF-u je važan. Stranice se slojevima proizvoda dodjeljuju prema položaju, a očekivani redoslijed stranica ovisi o vrsti proizvoda. Provjerite slijede li stranice u vašem PDF-u ispravan redoslijed slojeva za proizvod koji šaljete.

Važno: svaka stranica PDF-a mora odgovarati zahtijevanim dimenzijama za svoj sloj proizvoda i biti ispravno orijentirana. Postavite grafiku tako da vrh dizajna bude poravnat s vrhom stranice. Pogrešna veličina ili orijentacija stranice može u proizvodnji uzrokovati probleme sa skaliranjem, rotacijom ili poravnanjem.

Saznajte koliko će stajati dostava narudžbe i koliko će dugo biti na putu prije nego što je kreirate, prema istim pravilima po kojima Fabrixa obračunava samu narudžbu.

Da biste saznali u koje se zemlje varijanta proizvoda može dostaviti, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/shipping/countries sa svojim vjerodajnicama. Popis, poredan po nazivu, sadrži zemlje do kojih lokacija koja proizvodi varijantu ima tarifu dostave za paket za dostavu u koji se varijanta može zapakirati. Za zemlju koja nije na popisu ne postoji tarifa dostave za tu varijantu.

Parametri upita

Primjer zahtjeva

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'

Primjer 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

Da biste saznali koliko bi stajala dostava varijante proizvoda i koliko bi dugo bila na putu, pošaljite zahtjev GET na https://api.fabrixa.com/v2/integration/shipping/estimate sa svojim vjerodajnicama. Procjena slijedi pravila po kojima se obračunava narudžba: jedinice se pakiraju u pakete za dostavu lokacije koja proizvodi varijantu, a cijena svakog paketa izračunava se za rutu od te lokacije do odredišne zemlje. Ništa se ne naručuje niti rezervira, a narudžba se obračunava u trenutku kreiranja, pa se njezina cijena dostave može razlikovati ako se tarife u međuvremenu promijene.

Parametri upita

Primjer zahtjeva

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'

Primjer 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

Na zahtjev koji ne prođe validaciju odgovara se s 400 Bad Request i razlogom za svako polje, s istim porukama kao kod stavke narudžbe, na primjer The variant not found. Kada nijedan paket za dostavu ne može primiti jedinice, odgovor je 400 Bad Request s porukom No shipping package can carry the variant.

Fabrixa Studio alat je koji korisnicima omogućuje jednostavnu prilagodbu i personalizaciju proizvoda u stvarnom vremenu putem intuitivnog sučelja u kojem mogu izraditi ili učitati vlastite dizajne.

Fabrixa Studio idealan je za tvrtke koje nude proizvode po mjeri - kupcima omogućuje da vide svoj dizajn prije nego što dovrše narudžbu.

Fabrixa Studio možete ugraditi na svoje web-mjesto pomoću elementa iframe. Tako vaši kupci mogu personalizirati proizvode izravno na vašem web-mjestu tijekom kupnje.

Primjer iframea za ugradnju Fabrixa Studija:

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

Zamijenite vrijednosti za product_sku, cart_item_key i application_key svojim dinamičkim vrijednostima.

• application_key - jedinstveni ključ za autentifikaciju na Integration API-ju.
• product_sku - SKU varijante proizvoda, dohvaćen iz Integration API-ja.
• cart_item_key - jedinstvena vrijednost s platforme u koju je Studio ugrađen, koja identificira stavku košarice povezanu s proizvodom. Služi za spremanje korisnikovih personalizacija; pri kreiranju narudžbe identificira spremljene personalizacije i dodjeljuje ih narudžbi. Pogledajte primjer u nastavku.
• locale (neobavezno) - jezik sučelja Studija i njegovih poruka o pogreškama, npr. de_DE ili de. Bez njega se Studio otvara na jeziku preglednika kupca ako je podržan, inače na engleskom.

Zaglavlje Studija prikazuje naziv proizvoda kakav je u vašoj trgovini - isti naslov koji vide vaši kupci - a ispod njega opcije odabrane varijante. To je vlastita kopija proizvoda u vašoj trgovini, pa se naziv koji promijenite u Fabrixi prikazuje i u Studiju; locale ga ne prevodi.

Zahtjev za kreiranje narudžbe s 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": {
    "...": "..."
  }
}

Kada se unutar iframea klikne gumb Dodaj u košaricu, izvršava se sljedeća naredba:

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

Slično tome, kada se klikne gumb Natrag:

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

Metoda postMessage omogućuje komunikaciju između iframea i njegova nadređenog prozora preko različitih izvora (cross-origin), tako da iframe može obavijestiti nadređeni prozor o određenim radnjama korisnika.

Prvi argument metode postMessage podaci su koje želite poslati. Znakovni niz 'customizationFinished' označava da je korisnik završio personalizaciju i dodaje proizvod u košaricu. 'closeButtonClicked' označava da se korisnik odlučio vratiti.

U nadređenom prozoru osluškujte te poruke pomoću osluškivača događaja 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.');
        }
    }
});

Uvijek provjerite origin dolaznih poruka kako biste bili sigurni da dolaze iz pouzdanog izvora. Ovisno o primljenoj poruci izvršite potrebne radnje - ažurirajte korisničko sučelje, obradite košaricu i sl. Provjera vrijednosti origin ključna je za sigurnost - sprječava neovlaštene skripte u interakciji s vašom aplikacijom.

Nakon završetka personalizacije prikažite konačni dizajn pomoću URL-a pregleda u nastavku. Taj URL vraća sliku personaliziranog proizvoda, prikladnu kao vrijednost src u oznaci <img>. Idealno je za prikaz personaliziranog proizvoda u košarici, sažetku narudžbe ili bilo gdje u sučelju vaše trgovine.

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

Zamijenite {CART_ITEM_KEY} stvarnim ključem stavke košarice, a {APPLICATION_KEY} svojim valjanim ključem aplikacije.

Primjer upotrebe u oznaci 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 koristi webhookove kako bi vaš sustav obavijestila o događajima u stvarnom vremenu - ažuriranjima ili kreiranju narudžbi. Kada se dogodi neki događaj, Fabrixa na vaš poslužitelj šalje webhook s relevantnim informacijama. Vaš poslužitelj mora izložiti javni POST endpoint za obradu dolaznih webhookova.

Webhook zahtjev sadrži sljedeća zaglavlja koja vam pomažu identificirati i provjeriti dolazni zahtjev:

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

• content-type - za webhookove uvijek postavljeno na application/json.
• x-webhook-signature - HMAC-SHA256 potpis za provjeru zahtjeva.
• x-webhook-topic - vrsta događaja ili tema webhooka. Na primjer:
  • order.created - pokreće se kada se kreira nova narudžba.
  • order.updated - pokreće se kada se ažurira postojeća narudžba.

Webhookovi se šalju s User-Agentom Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); ako vaš endpoint filtrira automatizirani promet, dopustite ga. Da biste bili sigurni da zahtjev dolazi od Fabrixe, provjerite x-webhook-signature.

Fabrixa webhookovi obavještavaju vaš sustav o promjenama statusa narudžbe ili o aktivnostima. Svaki webhook pokreće određena vrijednost x-webhook-topic. Trenutačno podržane teme:

Primjer payloada koji se šalje s webhookom. Ovaj payload predstavlja ažuriranje narudžbe:

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

Nakon što se narudžba otpremi, shipments navodi svaku pošiljku s njezinim prijevoznikom (carrier), načinom dostave (method), statusom (status: pending, registered, collected, in transit, delivered, failed, returned ili canceled) i podacima za praćenje: tracking_number i tracking_url, a isto vrijedi i za svaki paket u packages kada pošiljka ima više paketa. Webhook order.updated šalje se svaki put kada se promijene status ili podaci za praćenje pošiljke, a GET /orders/{order_id} vraća isto polje.

Da biste bili sigurni da je webhook zahtjev autentičan i nepromijenjen, provjerite zaglavlje x-webhook-signature. To znači da ponovno izračunate HMAC-SHA256 potpis iz neobrađenog payloada zahtjeva i svojeg tajnog ključa te ga zatim usporedite s primljenim potpisom.

Primjer u čistom PHP-u

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

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

Zamijenite $yourSecret svojim zajedničkim tajnim ključem. Za usporedbu potpisa uvijek koristite hash_equals kako biste ublažili napade mjerenjem vremena (timing attacks).

Webhookovi se prema zadanim postavkama deaktiviraju nakon 10 neuspjelih pokušaja isporuke. Ako vaš endpoint vrati neuspješan status, primjerice 404 ili bilo koju pogrešku 5xx, webhook će pokušati ukupno 10 puta. Ako i dalje bude vraćao kod odgovora koji nije 2xx ili 3xx, bit će deaktiviran. Uspješni odgovori uključuju:

• 2xx - označava uspješnu obradu, npr. 200 OK.
• 301 i 302 - odgovori preusmjeravanja koji označavaju da je webhook uspješno obrađen ili proslijeđen.

Toplo preporučujemo da vaš endpoint što prije vrati statusni kod 200 OK kako bi potvrdio uspješan primitak webhooka. Iako se svaki odgovor 2xx ili 3xx smatra uspješnim, 200 je najčešće korišten i najpouzdaniji.

Da biste izbjegli istek vremena isporuke ili ponovne pokušaje, odmah vratite 200 OK, a payload webhooka obradite asinkrono, primjerice putem pozadinskog posla ili reda čekanja. Ako vaš endpoint predugo odgovara, isporuka se može smatrati neuspjelom čak i ako je odgovor na kraju uspješan.

Odgovori sa statusnim kodovima u rasponu 4xx ili 5xx, kao i istek vremena, pokreću ponovne pokušaje u skladu s mehanizmom ponavljanja.