Documentația de referință Fabrixa Integration API

Pentru a accesa Integration API, autentificați cererile folosind atât un token de acces al aplicației (Application Access Token), cât și o cheie a aplicației (Application Key):

Antetul Authorization

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Antetul cheii aplicației

X-Application-Key: APPLICATION_KEY

Exemplu de comandă 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'

Înlocuiți APPLICATION_ACCESS_TOKEN cu tokenul de acces real și APPLICATION_KEY cu cheia reală a aplicației.

Endpoint-urile Integration API sunt organizate după tipul de resursă și respectă stilul arhitectural REST. Fiecare endpoint reprezintă o resursă, iar acțiunile asupra resurselor se efectuează cu metode HTTP standard.

Toate cererile și răspunsurile Integration API sunt în format JSON, ceea ce oferă o interfață consecventă și ușor de folosit pentru lucrul cu API-ul.

Pentru detalii complete despre fiecare endpoint, inclusiv exemple de cereri și răspunsuri, consultați documentația Swagger.

Formatul răspunsului

Toate endpoint-urile returnează datele într-un format standardizat, cu următoarele obiecte:

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

Descrierea obiectelor din răspuns

Toate cererile API returnează coduri de stare HTTP care indică rezultatul cererii.

Corpul răspunsului de eroare

Exemplu de corp al unui răspuns de eroare:

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

errors conține detalii despre ce a eșuat. Array-ul messages enumeră descrierile erorilor. În cazul unui Bad Request, veți primi numele câmpurilor care nu au trecut validarea.

Integration API permite cel mult 30 de cereri pe aplicație pe minut.

Dacă depășiți această limită, veți primi un răspuns 429 Too Many Requests.

Toate răspunsurile Integration API includ antetul X-RateLimit-Remaining, cu numărul de cereri pe care clientul le mai poate face, și antetul X-RateLimit-Limit, cu numărul total de cereri permise pe minut.

Modul sandbox vă permite să testați integrarea de la un capăt la altul, înainte ca vreo comandă reală să fie produsă sau taxată. Se aplică întregului cont: comenzile din toate canalele de vânzare, inclusiv Integration API și magazinele Shopify și WooCommerce conectate, nu se produc și nu se debitează din soldul dvs. Contul dvs. este în mod sandbox cât timp starea sa este în așteptarea activării.

În modul sandbox puteți:

• să conectați magazinul Shopify sau WooCommerce ori să creați un canal Integration API;
• să adăugați produse și să verificați prețurile și estimările de livrare;
• să importați, să creați, să actualizați și să anulați comenzi;
• să verificați că niciuna dintre aceste comenzi nu se produce și nu se debitează din soldul dvs.;
• să verificați livrarea webhook-urilor și semnăturile.

Pentru a testa comenzi, adăugați produse din catalogul Fabrixa: deschideți un produs, faceți clic pe Vinde acest produs și alegeți variante și designuri. Acestea apar apoi la Produsele mele.

Pentru a trece contul în mod sandbox, deschideți Platform, mergeți la Setări → Companie → Mod sandbox și faceți clic pe Treceți în mod sandbox. Îl puteți activa și la adăugarea unui nou canal de vânzare, inclusiv a unui canal Integration API, sau puteți scrie la support@fabrixa.com și vă trecem noi contul în mod sandbox. Modul sandbox este disponibil doar pentru conturile active.

Când sunteți gata, activați singur contul în Platform la Setări → Companie → Mod sandbox. Puteți scrie și la support@fabrixa.com și îl activăm noi pentru dvs. Magazinele conectate și datele de acces API continuă să funcționeze, deci nu trebuie reconfigurat nimic.

După activare, toate comenzile noi merg în producție și se debitează din soldul dvs. Comenzile create înainte de activare rămân comenzi de test: nu se produc și nu se taxează niciodată, nici după activare.

Catalogul este tot ce produce Fabrixa. Produsele dvs. sunt produsele din catalog pe care le-ați adăugat în contul dvs. Fabrixa, cu propriile nume, descrieri, imagini și SKU-uri. O linie de comandă se referă la o variantă de produs - o mărime sau o versiune a unui produs - prin sku sau variant_id: o variantă a unuia dintre produsele dvs. sau o variantă din catalog comandată direct.

Pentru a lista produsele pe care le produce Fabrixa, trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/catalog/products cu datele dvs. de autentificare. Listează produsele active care au o variantă produsă în prezent de un partener de imprimare, și numai acele variante, fiecare cu SKU-ul, prețul de vânzare, dimensiunile și valorile opțiunilor sale.

Parametri de interogare

Exemplu de cerere

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'

Exemplu de răspuns

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

Câmpurile răspunsului

Pentru a lista categoriile în care este organizat catalogul, trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/catalog/categories cu datele dvs. de autentificare. Răspunsul conține categoriile de nivel superior, fiecare cu subcategoriile imbricate în sub_categories și numărul de produse din catalog pe care le conține în products_count. Transmiteți id-ul unei categorii ca category_id când răsfoiți catalogul, sau id-ul unei categorii de nivel superior ca parent_category_id pentru a obține dintr-odată produsele tuturor subcategoriilor sale.

Parametri de interogare

Exemplu de cerere

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'

Exemplu de răspuns

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

Pentru a lista produsele din contul dvs., trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/products cu datele dvs. de autentificare. Produsele dvs. sunt produsele din catalog pe care le-ați adăugat în contul dvs. Fabrixa: poartă numele, descrierile și imaginile pe care li le-ați dat acolo, iar variantele lor valorile SKU pe care le-ați ales. Sunt listate doar produsele active, zece pe pagină dacă nu transmiteți limit.

Parametri de interogare

Exemplu de cerere

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'

Exemplu de răspuns

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

Pentru a citi un singur produs, trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/products/{product_id}, unde {product_id} este id-ul său. Răspunsul conține aceleași câmpuri ca lista. Un produs care nu este în contul dvs., chiar și unul din catalog, răspunde 404 Not Found cu mesajul Product not found.

Câmpurile răspunsului

O variantă este o versiune a unui produs care poate fi comandată - o mărime, o culoare - și este ceea ce indică o linie de comandă, prin sku sau prin variant_id. Pentru a citi o variantă a unuia dintre produsele dvs., trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/variants/{variant_id}, unde {variant_id} este id-ul ei. O variantă a unui produs care nu este în contul dvs. răspunde 404 Not Found cu mesajul Variant not found.

Exemplu de cerere

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'

Exemplu de răspuns

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

Câmpurile răspunsului

O linie de comandă pentru această variantă, cu un PDF ale cărui pagini sunt straturile ei:

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

Ce variante pot fi comandate

Creați comenzi în Fabrixa din propriul magazin online sau din propria platformă, atașați fișierele de imprimare necesare și urmăriți fiecare articol pe parcursul onorării.

Pentru a crea o comandă prin Fabrixa Integration API, trimiteți o cerere POST către https://api.fabrixa.com/v2/integration/orders. Corpul cererii trebuie să includă:

Structura corpului cererii

Exemplu de cerere

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

Exemplu de răspuns

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

Pentru a actualiza o comandă, trimiteți o cerere PATCH către https://api.fabrixa.com/v2/integration/orders/{order_id}, unde {order_id} este id-ul comenzii în Fabrixa. Se modifică doar câmpurile pe care le trimiteți, iar statusul comenzii rămâne neschimbat. Răspunsul conține comanda actualizată. Puteți modifica:

Exemplu de cerere

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

Exemplu de răspuns

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

Pentru a anula o comandă, trimiteți o cerere POST fără corp către https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, unde {order_id} este id-ul comenzii în Fabrixa (câmpul numeric id al comenzii), nu numărul comenzii dumneavoastră. Răspunsul conține comanda cu statusul canceled, iar un webhook order.updated este trimis.

Exemplu de răspuns

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

Dacă comanda nu poate fi anulată, API-ul răspunde cu 412 Precondition Failed și un mesaj care explică motivul: statusul actual nu permite anularea (statusul este menționat în mesaj) sau producția a început deja.

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

O comandă este urmărită prin trei statusuri: câmpul status al comenzii, statusul de producție fulfillment_status și câmpul status al fiecărei expedieri din shipments. Fiecare modificare este trimisă în webhook-ul order.updated și returnată de GET /orders/{order_id}.

Statusurile comenzii

Valorile câmpului status al comenzii, în ordinea în care apar:

• imported - comanda a fost primită prin API. Orice comandă începe de aici.
• on hold - soldul nu acoperă costul comenzii. După reîncărcare, comanda revine la imported și continuă.
• accepted - comanda a fost acceptată și trimisă în producție.
• completed (final) - toate articolele au fost produse.
• canceled (final) - comanda a fost anulată. Acest lucru este posibil cât timp este imported, accepted sau on hold și producția nu a început încă.

Statusurile de onorare

Valorile câmpului fulfillment_status al comenzii și al fiecărui rând din comandă, în ordinea în care apar. Statusul avansează doar înainte, niciodată înapoi:

• unfulfilled - producția nu a început.
• scheduled - comanda este planificată într-un lot de producție. Din acest moment nu mai poate fi anulată.
• processing - producția este în curs.
• partially fulfilled - unele articole sunt gata, restul sunt încă în producție.
• fulfilled (final) - toate articolele sunt gata. Câmpul status al comenzii devine atunci completed.

O comandă în ansamblu nu este niciodată respinsă. Un singur articol poate fi respins la controlul de calitate din producție. Atunci este tipărit din nou: revine la unfulfilled și trece încă o dată prin producție, iar comanda își păstrează statusul și continuă de îndată ce articolul este gata.

Statusurile expedierii

Valorile câmpului status al fiecărei expedieri din shipments, în ordinea în care apar:

• pending - expedierea este în pregătire.
• registered - eticheta a fost creată la curier.
• collected - curierul a preluat coletul.
• in transit - coletul este pe drum.
• delivered (final) - coletul a fost livrat.

Excepții:

• failed - curierul a raportat o problemă.
• returned (final) - coletul ne-a fost returnat.
• canceled (final) - expedierea a fost anulată.

Pentru a obține statusul de onorare al unei comenzi, trimiteți o cerere GET către https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Răspunsul conține lista înregistrărilor de onorare asociate comenzii, inclusiv statusul fiecărui articol, detaliile produsului și progresul etapelor de producție.

Exemplu de răspuns

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

Răspunsul include o listă de înregistrări de onorare, fiecare dintre ele conținând:

Fiecare înregistrare de onorare corespunde unui anumit produs sau unei anumite variante de produs din comandă, iar fiecare exemplar al produsului din comandă are propria înregistrare de onorare - fiecare articol este urmărit individual pe tot parcursul producției.

Dacă pentru o comandă nu se returnează nicio înregistrare de onorare, comanda nu a intrat încă în etapa de procesare.

Când includeți fișiere sursă în comandă, asigurați-vă că acestea îndeplinesc următoarele cerințe:

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

Cerințe PDF și ordinea paginilor

Ordinea paginilor din PDF este importantă. Paginile sunt asociate straturilor produsului în funcție de poziție, iar ordinea așteptată a paginilor depinde de tipul produsului. Asigurați-vă că paginile din PDF respectă succesiunea corectă a straturilor pentru produsul pe care îl trimiteți.

Important: fiecare pagină PDF trebuie să aibă dimensiunile cerute pentru stratul de produs corespunzător și să fie orientată corect. Poziționați grafica astfel încât partea de sus a designului să fie aliniată cu partea de sus a paginii. O dimensiune sau o orientare incorectă a paginii poate cauza probleme de scalare, rotire sau aliniere în producție.

Aflați cât va costa livrarea unei comenzi și cât timp va fi pe drum înainte de a o plasa, calculată după aceleași reguli pe care Fabrixa le aplică comenzii înseși.

Pentru a afla în ce țări poate fi livrată o variantă de produs, trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/shipping/countries cu datele dvs. de autentificare. Lista cuprinde, sortate după nume, țările către care locația care produce varianta are un tarif de livrare pentru un colet de expediere în care poate fi ambalată varianta. O țară care nu apare în listă nu are tarif de livrare pentru variantă.

Parametri de interogare

Exemplu de cerere

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'

Exemplu de răspuns

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

Câmpurile răspunsului

Pentru a afla cât ar costa livrarea unei variante de produs și cât ar dura transportul, trimiteți o cerere GET la https://api.fabrixa.com/v2/integration/shipping/estimate cu datele dvs. de autentificare. Estimarea urmează regulile după care se calculează prețul unei comenzi: unitățile sunt ambalate în coletele de expediere ale locației care produce varianta, iar fiecare colet este tarifat pe ruta de la acea locație până în țara de destinație. Nu se comandă și nu se rezervă nimic, iar prețul unei comenzi se calculează în momentul plasării ei, așa că costul livrării poate diferi dacă tarifele se schimbă între timp.

Parametri de interogare

Exemplu de cerere

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'

Exemplu de răspuns

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

Câmpurile răspunsului

O cerere care nu trece validarea este refuzată cu 400 Bad Request și motivul pentru fiecare câmp, cu aceleași mesaje ca pentru o linie de comandă, de exemplu The variant not found. Când niciun colet de expediere nu poate transporta unitățile, răspunsul este 400 Bad Request cu mesajul No shipping package can carry the variant.

Fabrixa Studio este un instrument care le permite utilizatorilor să personalizeze produse în timp real, fără efort, printr-o interfață intuitivă în care își pot crea sau încărca propriile designuri.

Fabrixa Studio este ideal pentru afacerile care oferă produse personalizate - clienții își pot vizualiza designurile înainte de a finaliza comanda.

Puteți încorpora Fabrixa Studio în site-ul dumneavoastră folosind un iframe. Astfel, clienții își pot personaliza produsele direct pe site, în timpul finalizării comenzii.

Exemplu de iframe pentru încorporarea 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>

Înlocuiți valorile pentru product_sku, cart_item_key și application_key cu valorile dumneavoastră dinamice.

• application_key - cheie unică pentru autentificarea în Integration API.
• product_sku - SKU-ul variantei de produs, obținut din Integration API.
• cart_item_key - o valoare unică de la platforma care încorporează Studio, ce identifică articolul din coș asociat produsului. Este folosită pentru a salva personalizările utilizatorului; la crearea comenzii, identifică personalizările salvate și le atribuie comenzii. Consultați exemplul de mai jos.
• locale (opțional) - limba interfeței Studio și a mesajelor sale de eroare, de ex. de_DE sau de. Fără el, Studio se deschide în limba browserului cumpărătorului, dacă este acceptată, altfel în engleză.

Antetul Studio afișează numele produsului așa cum apare în magazinul dumneavoastră - același titlu pe care îl văd clienții dumneavoastră - iar dedesubt opțiunile variantei alese. Este copia proprie a produsului din magazinul dumneavoastră, așa că un nume pe care îl modificați în Fabrixa apare și în Studio; locale nu îl traduce.

Cerere de creare a unei comenzi cu 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": {
    "...": "..."
  }
}

Când se face clic pe butonul Adaugă în coș din iframe, se execută următoarea comandă:

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

În mod similar, la clic pe butonul Înapoi:

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

Metoda postMessage permite comunicarea cross-origin dintre iframe și fereastra părinte, astfel încât iframe-ul poate notifica fereastra părinte despre anumite acțiuni ale utilizatorului.

Primul argument al metodei postMessage reprezintă datele pe care doriți să le trimiteți. Șirul 'customizationFinished' indică faptul că utilizatorul a finalizat personalizarea și adaugă produsul în coș. 'closeButtonClicked' indică faptul că utilizatorul a ales să revină.

În fereastra părinte, ascultați aceste mesaje cu un listener pentru evenimentul 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.');
        }
    }
});

Verificați întotdeauna câmpul origin al mesajelor primite, pentru a vă asigura că provin dintr-o sursă de încredere. În funcție de mesajul primit, efectuați acțiunile necesare - actualizați interfața, procesați coșul etc. Validarea câmpului origin este esențială pentru securitate - împiedică scripturile neautorizate să interacționeze cu aplicația dumneavoastră.

După finalizarea personalizării, afișați designul final folosind URL-ul de previzualizare de mai jos. Acest URL returnează o imagine a produsului personalizat, pe care o puteți folosi ca valoare src într-un tag <img>. Este ideal pentru afișarea produsului personalizat în coș, în sumarul comenzii sau oriunde în interfața magazinului dumneavoastră.

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

Înlocuiți {CART_ITEM_KEY} cu cheia reală a articolului din coș și {APPLICATION_KEY} cu cheia validă a aplicației dumneavoastră.

Exemplu de utilizare într-un tag de imagine:

<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 folosește webhook-uri pentru a vă notifica sistemul despre evenimente în timp real - crearea sau actualizarea comenzilor. Când are loc un eveniment, Fabrixa trimite către serverul dumneavoastră un webhook cu informațiile relevante. Serverul trebuie să expună un endpoint POST public care să proceseze webhook-urile primite.

Cererea webhook include următoarele antete, care vă ajută să identificați și să validați cererea primită:

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

Detalierea antetelor

• content-type - întotdeauna application/json pentru webhook-uri.
• x-webhook-signature - semnătura HMAC-SHA256 pentru verificarea cererii.
• x-webhook-topic - tipul evenimentului sau topicul webhook-ului. De exemplu:
  • order.created - declanșat la crearea unei comenzi noi.
  • order.updated - declanșat la actualizarea unei comenzi existente.

Webhook-urile sunt trimise cu antetul User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); dacă endpoint-ul dumneavoastră filtrează traficul automatizat, permiteți-l. Pentru a vă asigura că o cerere provine de la Fabrixa, verificați antetul x-webhook-signature.

Webhook-urile Fabrixa vă notifică sistemul despre modificări ale statusului sau ale activității comenzilor. Fiecare webhook este declanșat de o anumită valoare a antetului x-webhook-topic. Topicuri acceptate în prezent:

Un exemplu de payload trimis cu webhook-ul. Acest payload reprezintă actualizarea unei comenzi:

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

După expedierea comenzii, shipments enumeră fiecare expediere cu carrier (transportatorul), method (metoda de livrare), status (pending, registered, collected, in transit, delivered, failed, returned sau canceled) și datele de urmărire: tracking_number și tracking_url, precum și aceleași date pentru fiecare colet din packages, atunci când o expediere are mai multe colete. Un webhook order.updated este trimis ori de câte ori se schimbă statusul sau datele de urmărire ale unei expedieri, iar GET /orders/{order_id} returnează același câmp.

Pentru a vă asigura că cererea webhook este autentică și nemodificată, verificați antetul x-webhook-signature. Pentru aceasta, recalculați semnătura HMAC-SHA256 pe baza payload-ului brut al cererii și a cheii dumneavoastră secrete, apoi comparați-o cu semnătura primită.

Exemplu în PHP simplu

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

Exemplu în Laravel

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

Înlocuiți $yourSecret cu cheia secretă partajată. Folosiți întotdeauna hash_equals pentru compararea semnăturilor, ca să preveniți atacurile de tip timing.

În mod implicit, webhook-urile sunt dezactivate după 10 încercări de livrare eșuate. Dacă endpoint-ul dumneavoastră returnează un status de eșec, precum 404 sau orice eroare 5xx, livrarea webhook-ului este reîncercată de până la 10 ori în total. Dacă endpoint-ul continuă să returneze un cod de răspuns diferit de 2xx sau 3xx, webhook-ul este dezactivat. Răspunsurile considerate reușite includ:

• 2xx - indică procesarea cu succes, de ex. 200 OK.
• 301 și 302 - răspunsuri de redirecționare care indică faptul că webhook-ul a fost gestionat sau redirecționat cu succes.

Vă recomandăm insistent ca endpoint-ul să returneze cât mai repede un cod de stare 200 OK, pentru a confirma primirea cu succes a webhook-ului. Deși orice răspuns 2xx sau 3xx este considerat reușit, 200 este cel mai des folosit și cel mai sigur.

Pentru a evita expirarea livrării sau reîncercările, returnați imediat 200 OK și procesați payload-ul webhook-ului asincron, de exemplu printr-un job în fundal sau printr-o coadă. Dacă endpoint-ul răspunde prea lent, livrarea poate fi considerată eșuată chiar dacă răspunsul este în cele din urmă reușit.

Răspunsurile cu coduri de stare din intervalul 4xx sau 5xx, precum și expirările, declanșează reîncercări conform mecanismului de reîncercare.