Dokumentacja interfejsu API integracji Fabrixa

Aby uzyskać dostęp do interfejsu API integracji, należy uwierzytelniać żądania przy użyciu zarówno tokenu dostępu do aplikacji, jak i klucza aplikacji:

Nagłówek autoryzacji

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Nagłówek klucza aplikacji

X-Application-Key: APPLICATION_KEY

Przykładowe polecenie 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'

Należy zastąpić APPLICATION_ACCESS_TOKEN rzeczywistym tokenem dostępu i APPLICATION_KEY rzeczywistym kluczem aplikacji.

Punkty końcowe interfejsu API integracji są zorganizowane według typu zasobu i są zgodne ze stylem architektonicznym RESTful. Każdy punkt końcowy reprezentuje zasób, a akcje na tych zasobach są wykonywane przy użyciu standardowych metod HTTP.

Wszystkie żądania i odpowiedzi Integration API są w formacie JSON, co zapewnia spójny i łatwy w użyciu interfejs do interakcji z API.

Pełne informacje o każdym endpoincie, w tym przykłady żądań i odpowiedzi, znajdą Państwo w naszej dokumentacji Swagger.

Forma odpowiedzi

Wszystkie punkty końcowe zwracają dane w ustandaryzowanym formacie z następującymi obiektami:

{
  "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 obiektów odpowiedzi

Wszystkie żądania API zwracają kody stanu HTTP, które zapewniają wgląd w odpowiedź.

Treść odpowiedzi na błąd

Przykład treści odpowiedzi na błąd:

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

errors zawiera szczegółowe informacje o tym, co się nie udało. Tablica messages zawiera opisy błędów. W przypadku nieprawidłowego żądania otrzymają Państwo nazwy pól, które nie zostały zweryfikowane.

Interfejs API integracji obsługuje limit 30 żądań na aplikację na minutę.

Po przekroczeniu tego limitu zwracana jest odpowiedź 429 Too Many Requests.

Wszystkie odpowiedzi interfejsu API integracji zawierają nagłówek X-RateLimit-Remaining określający liczbę żądań, które klient może jeszcze wykonać, oraz nagłówek X-RateLimit-Limit oznaczający całkowitą dozwoloną liczbę żądań na minutę.

Tryb piaskownicy pozwala przetestować integrację od początku do końca, zanim jakiekolwiek prawdziwe zamówienie zostanie wyprodukowane lub rozliczone. Obejmuje całe konto: zamówienia ze wszystkich kanałów sprzedaży, w tym z Integration API i podłączonych sklepów Shopify oraz WooCommerce, nie są produkowane i nie obciążają Twojego salda. Twoje konto jest w trybie piaskownicy, dopóki ma status oczekuje na aktywację.

W trybie piaskownicy możesz:

• podłączyć swój sklep Shopify lub WooCommerce albo utworzyć kanał Integration API;
• dodawać produkty oraz sprawdzać ceny i szacunki kosztów wysyłki;
• importować, tworzyć, aktualizować i anulować zamówienia;
• sprawdzić, że żadne z tych zamówień nie jest produkowane ani nie obciąża Twojego salda;
• sprawdzać dostarczanie webhooków i podpisy.

Aby przetestować zamówienia, dodaj produkty z katalogu Fabrixa: otwórz produkt, kliknij Sprzedawaj i wybierz warianty oraz projekty. Pojawią się one następnie w sekcji Moje produkty.

Aby przełączyć konto w tryb piaskownicy, otwórz Platform, przejdź do Ustawienia → Firma → Tryb piaskownicy i kliknij Przełącz w tryb piaskownicy. Możesz go też włączyć podczas dodawania nowego kanału sprzedaży, w tym kanału Integration API, albo napisać na support@fabrixa.com, a my przełączymy konto za Ciebie. Tryb piaskownicy jest dostępny tylko dla aktywnych kont.

Gdy będziesz gotowy, aktywuj konto samodzielnie w Platform w sekcji Ustawienia → Firma → Tryb piaskownicy. Możesz też napisać na support@fabrixa.com, a my aktywujemy je za Ciebie. Podłączone sklepy i dane uwierzytelniające API nadal działają, więc nic nie trzeba konfigurować od nowa.

Po aktywacji wszystkie nowe zamówienia trafiają do produkcji i obciążają Twoje saldo. Zamówienia utworzone przed aktywacją pozostają zamówieniami testowymi: nigdy nie są produkowane ani rozliczane, także po aktywacji.

Katalog to wszystko, co produkuje Fabrixa. Państwa produkty to produkty z katalogu, które dodali Państwo do swojego konta Fabrixa, z własnymi nazwami, opisami, zdjęciami i SKU. Pozycja zamówienia wskazuje wariant produktu - jeden rozmiar lub jedną wersję produktu - przez jego sku lub variant_id: wariant jednego z Państwa produktów albo wariant z katalogu zamówiony bezpośrednio.

Aby pobrać listę produktów, które produkuje Fabrixa, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/catalog/products ze swoimi danymi uwierzytelniającymi. Zawiera aktywne produkty mające wariant, który obecnie produkuje partner drukujący, i tylko te warianty - każdy ze swoim SKU, ceną sprzedaży, wymiarami i wartościami opcji.

Parametry zapytania

Przykładowe żądanie

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'

Przykładowa odpowiedź

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

Pola odpowiedzi

Aby pobrać listę kategorii, według których uporządkowany jest katalog, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/catalog/categories ze swoimi danymi uwierzytelniającymi. Odpowiedź zawiera kategorie najwyższego poziomu, każdą z podkategoriami zagnieżdżonymi w sub_categories i liczbą produktów katalogu w niej w products_count. Można przekazać id kategorii jako category_id podczas przeglądania katalogu albo id kategorii najwyższego poziomu jako parent_category_id, aby od razu pobrać produkty wszystkich jej podkategorii.

Parametry zapytania

Przykładowe żądanie

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'

Przykładowa odpowiedź

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

Aby pobrać listę produktów na swoim koncie, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/products ze swoimi danymi uwierzytelniającymi. Państwa produkty to produkty z katalogu, które dodali Państwo do swojego konta Fabrixa: mają nazwy, opisy i zdjęcia, które im tam Państwo nadali, a ich warianty - wybrane przez Państwa wartości SKU. Na liście są tylko aktywne produkty, po dziesięć na stronę, chyba że przekażą Państwo limit.

Parametry zapytania

Przykładowe żądanie

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'

Przykładowa odpowiedź

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

Aby odczytać jeden produkt, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/products/{product_id}, gdzie {product_id} to jego id. Odpowiedź zawiera te same pola co lista. Produkt, którego nie ma na Państwa koncie, nawet katalogowy, odpowiada 404 Not Found z komunikatem Product not found.

Pola odpowiedzi

Wariant to jedna wersja produktu, którą można zamówić - jeden rozmiar, jeden kolor - i to ją wskazuje pozycja zamówienia przez sku lub variant_id. Aby odczytać wariant jednego ze swoich produktów, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/variants/{variant_id}, gdzie {variant_id} to jego id. Wariant produktu, którego nie ma na Państwa koncie, odpowiada 404 Not Found z komunikatem Variant not found.

Przykładowe żądanie

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'

Przykładowa odpowiedź

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

Pola odpowiedzi

Pozycja zamówienia dla tego wariantu, z plikiem PDF, którego strony są jego warstwami:

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

Które warianty można zamówić

Zamówienia w Fabrixa można tworzyć z własnego sklepu lub platformy, dołączać do nich wymagane pliki do druku i śledzić każdy przedmiot podczas realizacji.

Aby utworzyć zamówienie za pośrednictwem API integracji Fabrixa, należy wysłać żądanie POST do https://api.fabrixa.com/v2/integration/orders. Treść wniosku musi zawierać:

Zapytaj o strukturę ciała

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Aby zaktualizować zamówienie, należy wysłać żądanie PATCH do https://api.fabrixa.com/v2/integration/orders/{order_id}, gdzie {order_id} to identyfikator zamówienia w Fabrixa. Zmieniają się tylko wysłane pola, a status zamówienia pozostaje bez zmian. Odpowiedź zawiera zaktualizowane zamówienie. Można zmienić:

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Aby anulować zamówienie, należy wysłać żądanie POST bez treści do https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, gdzie {order_id} to identyfikator zamówienia w Fabrixa (liczbowe pole id zamówienia), a nie Państwa numer zamówienia. Odpowiedź zawiera zamówienie ze statusem canceled, a webhook order.updated zostaje wysłany.

Przykładowa odpowiedź

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

Jeśli zamówienia nie można anulować, API odpowiada kodem 412 Precondition Failed i komunikatem z przyczyną: jego obecny status na to nie pozwala (status jest podany w komunikacie) albo produkcja już się rozpoczęła.

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

Zamówienie jest śledzone za pomocą trzech statusów: pola status zamówienia, jego statusu produkcji fulfillment_status oraz pola status każdej przesyłki w shipments. Każda zmiana jest wysyłana w webhooku order.updated i zwracana przez GET /orders/{order_id}.

Statusy zamówień

Wartości pola status zamówienia w kolejności, w jakiej występują:

• imported - zamówienie zostało przyjęte przez API. Każde zamówienie zaczyna się tutaj.
• on hold - saldo nie pokrywa kosztu zamówienia. Po jego doładowaniu zamówienie wraca do imported i jest realizowane dalej.
• accepted - zamówienie zostało zaakceptowane i trafia do produkcji.
• completed (końcowy) - wszystkie produkty zostały wyprodukowane.
• canceled (końcowy) - zamówienie zostało anulowane. Jest to możliwe, dopóki ma status imported, accepted lub on hold, a produkcja jeszcze się nie rozpoczęła.

Statusy realizacji

Wartości pola fulfillment_status zamówienia i każdej pozycji zamówienia w kolejności, w jakiej występują. Status zmienia się tylko do przodu, nigdy wstecz:

• unfulfilled - produkcja się nie rozpoczęła.
• scheduled - zamówienie zostało zaplanowane w partii produkcyjnej. Od tej chwili nie można go już anulować.
• processing - trwa produkcja.
• partially fulfilled - część produktów jest gotowa, pozostałe są jeszcze w produkcji.
• fulfilled (końcowy) - wszystkie produkty są gotowe. Wtedy status zamówienia zmienia się na completed.

Zamówienie jako całość nigdy nie jest odrzucane. Pojedynczy produkt może zostać odrzucony podczas kontroli jakości w trakcie produkcji. Jest wtedy drukowany ponownie: wraca do unfulfilled i jeszcze raz przechodzi przez produkcję, a zamówienie zachowuje swój status i jest realizowane dalej, gdy produkt będzie gotowy.

Statusy przesyłek

Wartości pola status każdej przesyłki w shipments w kolejności, w jakiej występują:

• pending - przesyłka jest przygotowywana.
• registered - etykieta została utworzona u przewoźnika.
• collected - przewoźnik odebrał paczkę.
• in transit - paczka jest w drodze.
• delivered (końcowy) - paczka została doręczona.

Wyjątki:

• failed - przewoźnik zgłosił problem.
• returned (końcowy) - paczka została do nas zwrócona.
• canceled (końcowy) - przesyłka została anulowana.

Aby uzyskać status realizacji konkretnego zamówienia, należy wysłać żądanie GET do https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Odpowiedź zawiera listę realizacji powiązanych z zamówieniem, w tym status każdego artykułu, szczegóły produktu i postęp na etapie produkcji.

Przykładowa odpowiedź

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

Odpowiedź zawiera listę spełnień, z których każde zawiera:

Każdy zapis realizacji odpowiada konkretnemu produktowi lub wariantowi produktu w ramach zamówienia, a każdy egzemplarz produktu w zamówieniu ma swój własny zapis realizacji - każdy artykuł jest śledzony indywidualnie przez całą produkcję.

Jeżeli za zamówienie nie zwrócono żadnych realizacji, oznacza to, że zamówienie nie weszło jeszcze w fazę realizacji.

Dołączając do zamówienia pliki źródłowe, należy upewnić się, że spełniają one następujące wymagania:

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

Wymagania dotyczące plików PDF i kolejność stron

Kolejność stron w pliku PDF jest istotna. Strony dopasowywane są do warstw produktów według pozycji, a oczekiwana kolejność stron zależy od rodzaju produktu. Należy upewnić się, że strony w pliku PDF mają prawidłową kolejność warstw dla przesyłanego produktu.

Ważne: każda strona PDF musi odpowiadać wymaganym wymiarom dla warstwy produktu i być prawidłowo zorientowana. Grafikę należy umieścić tak, aby góra projektu była wyrównana z górą strony. Nieprawidłowy rozmiar strony lub orientacja może powodować problemy ze skalowaniem, rotacją lub wyrównaniem w produkcji.

Można sprawdzić, ile będzie kosztować wysyłka zamówienia i jak długo będzie w drodze, zanim zostanie ono złożone, według tych samych zasad, według których Fabrixa wycenia samo zamówienie.

Aby sprawdzić, do których krajów można wysłać wariant produktu, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/shipping/countries ze swoimi danymi uwierzytelniającymi. Lista, posortowana według nazwy, zawiera kraje, do których lokalizacja, która produkuje wariant, ma stawkę wysyłki dla paczki wysyłkowej, w którą można zapakować wariant. Jeśli kraju nie ma na liście, nie ma do niego stawki wysyłki dla tego wariantu.

Parametry zapytania

Przykładowe żądanie

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'

Przykładowa odpowiedź

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

Pola odpowiedzi

Aby sprawdzić, ile kosztowałaby wysyłka wariantu produktu i jak długo przesyłka byłaby w drodze, należy wysłać żądanie GET na https://api.fabrixa.com/v2/integration/shipping/estimate ze swoimi danymi uwierzytelniającymi. Wycena opiera się na tych samych zasadach, według których wyceniane jest zamówienie: sztuki są pakowane w paczki wysyłkowe lokalizacji, która produkuje wariant, a każda paczka jest wyceniana według trasy z tej lokalizacji do kraju docelowego. Nic nie zostaje zamówione ani zarezerwowane, a zamówienie jest wyceniane w chwili złożenia, więc koszt jego wysyłki może być inny, jeśli w międzyczasie zmienią się stawki.

Parametry zapytania

Przykładowe żądanie

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'

Przykładowa odpowiedź

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

Pola odpowiedzi

Na żądanie, które nie przejdzie walidacji, odpowiedzią jest 400 Bad Request z powodem dla każdego pola i tymi samymi komunikatami co dla pozycji zamówienia, na przykład The variant not found. Gdy żadna paczka wysyłkowa nie pomieści sztuk, odpowiedzią jest 400 Bad Request z komunikatem No shipping package can carry the variant.

Fabrixa Studio to narzędzie, które pozwala użytkownikom bezproblemowo dostosowywać i personalizować produkty w czasie rzeczywistym za pomocą intuicyjnego interfejsu, w którym użytkownicy mogą tworzyć lub przesyłać własne projekty.

Fabrixa Studio jest idealne dla firm oferujących produkty niestandardowe – umożliwiając klientom wizualizację swoich projektów przed sfinalizowaniem zamówienia.

Mogą Państwo osadzić Fabrixa Studio na swojej stronie internetowej za pomocą iframe. Dzięki temu Państwa klienci mogą personalizować produkty bezpośrednio na Państwa stronie podczas realizacji transakcji.

Przykładowy element iframe do osadzenia 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>

Wartości product_sku, cart_item_key i application_key należy zastąpić własnymi wartościami dynamicznymi.

• application_key - unikalny klucz do uwierzytelnienia w Integration API.
• product_sku - SKU wariantu produktu pobrany z Integration API.
• cart_item_key - unikalna wartość z platformy embedingowej identyfikująca pozycję koszyka powiązaną z produktem. Służy do zapisywania dostosowań użytkownika; podczas tworzenia zamówienia identyfikuje zapisane dostosowania i przypisuje je do zamówienia. Przykład znajduje się poniżej.
• locale (opcjonalnie) - język interfejsu Studio i jego komunikatów o błędach, np. de_DE lub de. Bez niego Studio otwiera się w języku przeglądarki kupującego, jeśli jest obsługiwany, w przeciwnym razie po angielsku.

Nagłówek Studio pokazuje nazwę produktu taką, jaka jest w Państwa sklepie - ten sam tytuł, który widzą Państwa klienci - a pod nią opcje wybranego wariantu. To własna kopia produktu w Państwa sklepie, więc nazwa zmieniona w Fabrixa pojawia się też w Studio; locale jej nie tłumaczy.

Prośba o utworzenie zamówienia za pomocą 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": {
    "...": "..."
  }
}

Po kliknięciu przycisku Dodaj do koszyka wewnątrz elementu iframe wykonywane jest następujące polecenie:

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

Podobnie po kliknięciu przycisku Back:

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

Metoda postMessage ułatwia komunikację między źródłami między ramką iframe a jej oknem nadrzędnym, umożliwiając powiadamianie elementu nadrzędnego o określonych działaniach użytkownika.

Pierwszym argumentem postMessage są dane, które mają zostać wysłane. Ciąg 'customizationFinished' wskazuje, że użytkownik zakończył dostosowywanie i dodaje produkt do koszyka. 'closeButtonClicked' wskazuje, że użytkownik zdecydował się wrócić.

W oknie nadrzędnym należy nasłuchiwać tych komunikatów za pomocą detektora zdarzeń 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.');
        }
    }
});

Należy zawsze sprawdzać origin przychodzących wiadomości, aby upewnić się, że pochodzą z zaufanego źródła. W zależności od otrzymanej wiadomości należy wykonać niezbędne działania - zaktualizować interfejs użytkownika, przetworzyć koszyk itp. Walidacja origin jest kluczowa dla bezpieczeństwa - zapobiega interakcji nieautoryzowanych skryptów z Państwa aplikacją.

Po zakończeniu dostosowywania można wyświetlić ostateczny projekt, korzystając z poniższego adresu URL podglądu. Ten adres URL zwraca obraz spersonalizowanego produktu, odpowiedni jako wartość src w tagu <img>. Idealny do pokazania spersonalizowanego produktu w koszyku, podsumowaniu zamówienia lub w dowolnym miejscu interfejsu sklepu.

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

Należy zastąpić {CART_ITEM_KEY} rzeczywistym kluczem pozycji koszyka i {APPLICATION_KEY} prawidłowym kluczem aplikacji.

Przykładowe użycie w tagu obrazu:

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

Webhooki są używane przez firmę Fabrixa do powiadamiania Państwa systemu o zdarzeniach w czasie rzeczywistym - aktualizacjach zamówień lub kreacjach. Kiedy nastąpi zdarzenie, Fabrixa wysyła webhook na Państwa serwer zawierający odpowiednie informacje. Państwa serwer musi udostępniać publiczny punkt końcowy POST, aby obsługiwać przychodzące webhooki.

Żądanie webhooka zawiera następujące nagłówki, które pomogą Państwu zidentyfikować i zweryfikować przychodzące żądanie:

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

Podział nagłówka

• content-type - zawsze ustawione na application/json dla webhooków.
• x-webhook-signature - podpis HMAC-SHA256 do weryfikacji żądania.
• x-webhook-topic - typ zdarzenia lub temat webhooka. Na przykład:
  • order.created - wyzwalane w momencie utworzenia nowego zamówienia.
  • order.updated - wyzwalane w przypadku aktualizacji istniejącego zamówienia.

Webhooki są wysyłane z User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); jeśli Państwa endpoint filtruje ruch automatyczny, należy na niego zezwolić. Aby mieć pewność, że żądanie pochodzi od Fabrixa, należy zweryfikować x-webhook-signature.

Webhooki Fabrixa powiadamiają Państwa system o zmianach w statusie zamówienia lub aktywności. Każdy webhook jest wyzwalany przez określoną wartość x-webhook-topic. Aktualnie obsługiwane tematy:

Przykład ładunku wysłanego za pomocą webhooka. Ten ładunek reprezentuje aktualizację zamówienia:

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

Gdy zamówienie zostanie wysłane, shipments zawiera każdą przesyłkę z przewoźnikiem (carrier), metodą wysyłki (method), statusem (status: pending, registered, collected, in transit, delivered, failed, returned lub canceled) i śledzeniem: tracking_number i tracking_url, a także tymi samymi danymi dla każdej paczki w packages, gdy przesyłka ma ich kilka. Przy każdej zmianie statusu lub śledzenia przesyłki wysyłany jest webhook order.updated, a GET /orders/{order_id} zwraca to samo pole.

Aby upewnić się, że żądanie elementu webhook jest autentyczne i niezmienione, należy sprawdzić nagłówek x-webhook-signature. Obejmuje to ponowne obliczenie podpisu HMAC-SHA256 przy użyciu nieprzetworzonego ładunku żądania i tajnego klucza, a następnie porównanie go z otrzymanym podpisem.

Przykład surowego 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');
}

Przykład Laravela

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

Należy zastąpić $yourSecret swoim wspólnym tajnym kluczem. Należy zawsze używać hash_equals do porównywania podpisów, aby złagodzić ataki czasowe.

Domyślnie webhooki są wyłączone po 10 nieudanych próbach dostarczenia. Jeśli punkt końcowy zwróci status niepowodzenia, taki jak 404 lub dowolny błąd 5xx, element webhook spróbuje ponownie w sumie 10 razy. Jeśli w dalszym ciągu będzie zwracał kod odpowiedzi inny niż 2xx lub inny niż 3xx, zostanie dezaktywowany. Pomyślne odpowiedzi obejmują:

• 2xx - oznacza pomyślne przetwarzanie, np.: 200 OK.
• 301 i 302 - odpowiedzi przekierowań wskazujące, że webhook został pomyślnie obsłużony lub przesłany dalej.

Zdecydowanie zalecamy, aby punkt końcowy zwrócił kod stanu 200 OK tak szybko, jak to możliwe, aby potwierdzić pomyślne otrzymanie elementu webhook. Chociaż każdą odpowiedź 2xx lub 3xx uważa się za pomyślną, najczęściej używaną i niezawodną jest odpowiedź 200.

Aby uniknąć przekroczenia limitu czasu dostarczania lub ponownych prób, należy natychmiast zwrócić 200 OK i obsłużyć asynchroniczne przetwarzanie ładunku elementu webhook, na przykład za pośrednictwem zadania lub kolejki w tle. Jeśli odpowiedź punktu końcowego trwa zbyt długo, może to zostać uznane za awarię, nawet jeśli odpowiedź ostatecznie zakończy się sukcesem.

Odpowiedzi z kodami stanu z zakresu 4xx lub 5xx lub przekroczenia limitu czasu będą wyzwalać ponowne próby zgodnie z mechanizmem ponawiania.