Riferimento API Fabrixa Integration

Per accedere all’API Integration, autentica le richieste usando sia un Application Access Token sia una Application Key:

Intestazione dell'autorizzazione

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Intestazione della chiave dell'applicazione

X-Application-Key: APPLICATION_KEY

Esempio di comando 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'

Sostituisci APPLICATION_ACCESS_TOKEN con il tuo token di accesso effettivo e APPLICATION_KEY con la tua chiave di applicazione effettiva.

Gli endpoint dell’API Integration sono organizzati per tipo di risorsa e seguono lo stile REST. Ogni endpoint rappresenta una risorsa e le azioni sono eseguite con metodi HTTP standard.

Tutte le richieste e risposte dell’API Integration usano JSON, offrendo un’interfaccia coerente e semplice.

Per i dettagli completi su ogni endpoint, inclusi esempi di richieste e risposte, consulta il nostro Swagger documentation.

Formato della risposta

Tutti gli endpoint restituiscono i dati in un formato standardizzato con questi oggetti:

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

Descrizione degli oggetti di risposta

Tutte le richieste API restituiscono codici di stato HTTP che forniscono informazioni dettagliate sulla risposta.

Corpo della risposta all'errore

Un esempio di corpo della risposta all'errore:

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

errors contiene dettagli su ciò che non è riuscito. L'array messages elenca le descrizioni degli errori. Per una richiesta errata, riceverai i nomi dei campi che non hanno superato la convalida.

L'API di integrazione supporta un limite di 30 richieste per applicazione al minuto.

Se superi questo limite riceverai una risposta 429 Too Many Requests.

Tutte le risposte dell'API di integrazione includono l'intestazione X-RateLimit-Remaining, il numero di richieste che il client può ancora effettuare e l'intestazione X-RateLimit-Limit, il totale consentito al minuto.

La modalità sandbox ti permette di testare la tua integrazione da cima a fondo prima che qualsiasi ordine reale venga prodotto o addebitato. Si applica all’intero account: gli ordini di tutti i canali di vendita, inclusi l’Integration API e i negozi Shopify e WooCommerce collegati, non vengono prodotti né addebitati sul tuo saldo. Il tuo account è in modalità sandbox finché il suo stato è in attesa di attivazione.

In modalità sandbox puoi:

• collegare il tuo negozio Shopify o WooCommerce oppure creare un canale Integration API;
• aggiungere prodotti e verificare prezzi e stime di spedizione;
• importare, creare, aggiornare e annullare ordini;
• verificare che nessuno di questi ordini venga prodotto o addebitato sul tuo saldo;
• verificare la consegna dei webhook e le firme.

Per testare gli ordini, aggiungi prodotti dal catalogo Fabrixa: apri un prodotto, fai clic su Vendi questo prodotto e scegli varianti e design. Compariranno poi in I miei prodotti.

Per passare il tuo account alla modalità sandbox, apri Platform, vai in Impostazioni → Azienda → Modalità sandbox e fai clic su Passa alla modalità sandbox. Puoi attivarla anche quando aggiungi un nuovo canale di vendita, compreso un canale Integration API, oppure scrivere a support@fabrixa.com e lo passeremo noi alla modalità sandbox. La modalità sandbox è disponibile solo per gli account attivi.

Quando sei pronto, attiva l’account da solo in Platform in Impostazioni → Azienda → Modalità sandbox. Puoi anche scrivere a support@fabrixa.com e lo attiveremo noi per te. I negozi collegati e le credenziali API continuano a funzionare, quindi non serve riconfigurare nulla.

Dopo l’attivazione, tutti i nuovi ordini vanno in produzione e vengono addebitati sul tuo saldo. Gli ordini creati prima dell’attivazione restano ordini di prova: non vengono mai prodotti né addebitati, nemmeno dopo l’attivazione.

Il catalogo è tutto ciò che Fabrixa produce. I tuoi prodotti sono i prodotti del catalogo che hai aggiunto al tuo account Fabrixa, con i tuoi nomi, descrizioni, immagini e SKU. Una riga d'ordine indica una variante di prodotto - una taglia o una versione di un prodotto - tramite il suo sku o variant_id: una variante di uno dei tuoi prodotti, oppure una variante del catalogo ordinata direttamente.

Per elencare i prodotti che Fabrixa produce, invia una richiesta GET a https://api.fabrixa.com/v2/integration/catalog/products con le tue credenziali. Elenca i prodotti attivi che hanno una variante che un partner di stampa produce attualmente, e solo quelle varianti, ciascuna con il suo SKU, prezzo di vendita, dimensioni e valori delle opzioni.

Parametri della query

Richiesta di campione

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'

Esempio di risposta

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

Campi della risposta

Per elencare le categorie in cui è organizzato il catalogo, invia una richiesta GET a https://api.fabrixa.com/v2/integration/catalog/categories con le tue credenziali. La risposta contiene le categorie di primo livello, ciascuna con le sue sottocategorie annidate in sub_categories e il numero di prodotti del catalogo che contiene in products_count. Passa l'id di una categoria come category_id quando sfogli il catalogo, oppure l'id di una categoria di primo livello come parent_category_id per ottenere in una volta i prodotti di tutte le sue sottocategorie.

Parametri della query

Richiesta di campione

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'

Esempio di risposta

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

Per elencare i prodotti del tuo account, invia una richiesta GET a https://api.fabrixa.com/v2/integration/products con le tue credenziali. I tuoi prodotti sono i prodotti del catalogo che hai aggiunto al tuo account Fabrixa: portano i nomi, le descrizioni e le immagini che hai dato loro lì, e le loro varianti i valori di SKU che hai scelto. Vengono elencati solo i prodotti attivi, dieci per pagina a meno che non passi limit.

Parametri della query

Richiesta di campione

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'

Esempio di risposta

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

Per leggere un singolo prodotto, invia una richiesta GET a https://api.fabrixa.com/v2/integration/products/{product_id}, dove {product_id} è il suo id. La risposta contiene gli stessi campi dell'elenco. Un prodotto che non è nel tuo account, anche uno del catalogo, risponde 404 Not Found con il messaggio Product not found.

Campi della risposta

Una variante è una versione ordinabile di un prodotto - una taglia, un colore - ed è ciò che indica una riga d'ordine, tramite sku o variant_id. Per leggere una variante di uno dei tuoi prodotti, invia una richiesta GET a https://api.fabrixa.com/v2/integration/variants/{variant_id}, dove {variant_id} è il suo id. Una variante di un prodotto che non è nel tuo account risponde 404 Not Found con il messaggio Variant not found.

Richiesta di campione

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'

Esempio di risposta

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

Campi della risposta

Una riga d'ordine per questa variante, con un PDF le cui pagine sono i suoi livelli:

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

Quali varianti si possono ordinare

Crea ordini in Fabrixa dal tuo storefront o dalla tua piattaforma, allega i file di stampa richiesti e segui ogni articolo durante il fulfilment.

Per creare un ordine tramite la Fabrixa Integration API, invia una richiesta POST a https://api.fabrixa.com/v2/integration/orders. Il request body deve includere:

Richiedi struttura corporea

Richiesta di campione

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

Esempio di risposta

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

Per aggiornare un ordine, invia una richiesta PATCH a https://api.fabrixa.com/v2/integration/orders/{order_id}, dove {order_id} è l’id Fabrixa dell’ordine. Cambiano solo i campi che invii e lo stato dell’ordine resta invariato. La risposta contiene l’ordine aggiornato. Puoi modificare:

Richiesta di campione

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

Esempio di risposta

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

Per annullare un ordine, invia una richiesta POST senza body a https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, dove {order_id} è l’id Fabrixa dell’ordine (il campo numerico id dell’ordine), non il tuo numero d’ordine. La risposta contiene l’ordine con lo stato canceled e viene inviato un webhook order.updated.

Esempio di risposta

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

Se l’ordine non può essere annullato, l’API risponde con 412 Precondition Failed e un messaggio che ne indica il motivo: il suo stato attuale non lo consente (lo stato è indicato nel messaggio) oppure la produzione è già iniziata.

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

Un ordine viene seguito tramite tre stati: lo status dell'ordine, il suo stato di produzione fulfillment_status e lo status di ogni spedizione in shipments. Ogni modifica viene inviata nel webhook order.updated e restituita da GET /orders/{order_id}.

Stati degli ordini

Lo status di un ordine, nell'ordine in cui viene raggiunto:

• imported - l'ordine è stato ricevuto tramite l'API. Ogni ordine parte da qui.
• on hold - il saldo non copre il costo dell'ordine. Una volta ricaricato, l'ordine torna a imported e prosegue.
• accepted - l'ordine è stato accettato e passa in produzione.
• completed (definitivo) - tutti gli articoli sono stati prodotti.
• canceled (definitivo) - l'ordine è stato annullato. È possibile finché è imported, accepted o on hold e la produzione non è ancora iniziata.

Stati di adempimento

Lo fulfillment_status di un ordine e di ogni riga d'ordine, nell'ordine in cui viene raggiunto. Avanza soltanto, non torna mai indietro:

• unfulfilled - la produzione non è iniziata.
• scheduled - l'ordine è pianificato in un lotto di produzione. Da questo momento non può più essere annullato.
• processing - la produzione è in corso.
• partially fulfilled - alcuni articoli sono pronti, gli altri sono ancora in produzione.
• fulfilled (definitivo) - tutti gli articoli sono pronti. Lo status dell'ordine diventa quindi completed.

Un ordine nel suo insieme non viene mai rifiutato. Un singolo articolo può essere rifiutato al controllo qualità durante la produzione. Viene quindi ristampato: torna a unfulfilled e ripassa in produzione, mentre l'ordine mantiene il suo stato e prosegue quando l'articolo è pronto.

Stati della spedizione

Lo status di ogni spedizione in shipments, nell'ordine in cui viene raggiunto:

• pending - la spedizione è in preparazione.
• registered - l'etichetta è stata creata presso il corriere.
• collected - il corriere ha ritirato il pacco.
• in transit - il pacco è in viaggio.
• delivered (definitivo) - il pacco è stato consegnato.

Eccezioni:

• failed - il corriere ha segnalato un problema.
• returned (definitivo) - il pacco ci è stato restituito.
• canceled (definitivo) - la spedizione è stata annullata.

Per ottenere lo stato fulfilment di un ordine specifico, invia una richiesta GET a https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. La risposta fornisce i fulfilment associati all’ordine, inclusi stato degli articoli, dettagli prodotto e avanzamento degli step di produzione.

Esempio di risposta

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

La risposta include un elenco di adempimenti, ciascuno dei quali prevede:

Ogni record di evasione corrisponde a un prodotto specifico o a una variante di prodotto all'interno dell'ordine e ogni copia del prodotto nell'ordine ha il proprio record di evasione: ogni articolo viene tracciato individualmente durante tutta la produzione.

Se per un ordine non vengono restituiti adempimenti, l'ordine non è ancora entrato nella fase di elaborazione.

Quando includi source files nell’ordine, assicurati che rispettino i seguenti requisiti:

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

Requisiti PDF e ordine delle pagine

L'ordine delle pagine nel PDF è importante. Le pagine vengono abbinate ai livelli del prodotto in base alla posizione e l'ordine delle pagine previsto dipende dal tipo di prodotto. Assicurati che le pagine del tuo PDF seguano la sequenza di livelli corretta per il prodotto che stai inviando.

Importante: ogni pagina PDF deve corrispondere alle dimensioni richieste per il relativo livello di prodotto ed essere orientata correttamente. Posiziona il disegno in modo che la parte superiore del disegno sia allineata con la parte superiore della pagina. Dimensioni o orientamento della pagina errati possono causare problemi di ridimensionamento, rotazione o allineamento nella produzione.

Scopri quanto costerà la spedizione di un ordine e per quanto tempo sarà in viaggio prima di effettuarlo, calcolata con le stesse regole che Fabrixa applica all'ordine stesso.

Per sapere in quali paesi può essere spedita una variante di prodotto, invia una richiesta GET a https://api.fabrixa.com/v2/integration/shipping/countries con le tue credenziali. L'elenco, ordinato per nome, contiene i paesi verso cui la sede che produce la variante ha una tariffa di spedizione per un pacco di spedizione in cui la variante può essere imballata. Un paese che non compare nell'elenco non ha alcuna tariffa di spedizione per la variante.

Parametri della query

Richiesta di campione

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'

Esempio di risposta

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

Campi della risposta

Per sapere quanto costerebbe spedire una variante di prodotto e per quanto tempo sarebbe in viaggio, invia una richiesta GET a https://api.fabrixa.com/v2/integration/shipping/estimate con le tue credenziali. La stima segue le regole con cui viene calcolato il prezzo di un ordine: le unità vengono imballate nei pacchi di spedizione della sede che produce la variante, e il prezzo di ogni pacco viene calcolato sulla tratta da quella sede al paese di destinazione. Nulla viene ordinato né riservato, e il prezzo di un ordine viene calcolato al momento in cui lo effettui, quindi il costo della sua spedizione può risultare diverso se nel frattempo le tariffe cambiano.

Parametri della query

Richiesta di campione

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'

Esempio di risposta

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

Campi della risposta

Una richiesta che non supera la convalida riceve come risposta 400 Bad Request e il motivo per ciascun campo, con gli stessi messaggi di una riga d'ordine, per esempio The variant not found. Quando nessun pacco di spedizione può contenere le unità, la risposta è 400 Bad Request con il messaggio No shipping package can carry the variant.

Fabrixa Studio è uno strumento che consente agli utenti di personalizzare e personalizzare facilmente i prodotti in tempo reale con un'interfaccia intuitiva in cui gli utenti possono creare o caricare i propri progetti.

Fabrixa Studio è ideale per le aziende che offrono prodotti personalizzati, consentendo ai clienti di visualizzare i propri progetti prima di finalizzare gli ordini.

Puoi incorporare Fabrixa Studio nel tuo sito usando un iframe. Questo permette ai clienti di personalizzare i prodotti direttamente sul sito durante il checkout.

Esempio di iframe per incorporare 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>

Sostituisci i valori per product_sku, cart_item_key e application_key con i tuoi valori dinamici.

• application_key: chiave univoca per l'autenticazione all'API di integrazione.
• product_sku: lo SKU della variante di prodotto, recuperato dall'API di integrazione.
• cart_item_key: un valore univoco dalla piattaforma di incorporamento che identifica l'articolo del carrello associato al prodotto. Utilizzato per salvare le personalizzazioni dell'utente; durante la creazione dell'ordine identifica le personalizzazioni salvate e le assegna all'ordine. Vedi l'esempio qui sotto.
• locale (facoltativo): la lingua dell'interfaccia di Studio e dei suoi messaggi di errore, ad es. de_DE o de. Senza di esso, Studio si apre nella lingua del browser dell'acquirente se è supportata, altrimenti in inglese.

L'intestazione di Studio mostra il nome del prodotto così come è nel tuo negozio - lo stesso titolo che vedono i tuoi clienti - con sotto le opzioni della variante scelta. È la copia del prodotto propria del tuo negozio, quindi un nome che modifichi in Fabrixa compare anche in Studio; locale non lo traduce.

Richiesta di creazione di un ordine con 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": {
    "...": "..."
  }
}

Quando si fa clic sul pulsante Aggiungi al carrello all'interno dell'iframe, viene eseguito il seguente comando:

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

Allo stesso modo, quando si fa clic sul pulsante Indietro:

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

Il metodo postMessage facilita la comunicazione multiorigine tra l'iframe e la sua finestra principale, consentendogli di notificare al genitore azioni specifiche dell'utente.

Il primo argomento di postMessage sono i dati che desideri inviare. La stringa 'customizationFinished' indica che l'utente ha finalizzato la personalizzazione e sta aggiungendo il prodotto al carrello. 'closeButtonClicked' indica che l'utente ha scelto di tornare indietro.

Nella finestra principale, ascolta questi messaggi utilizzando il listener di eventi 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.');
        }
    }
});

Controlla sempre origin dei messaggi in arrivo per assicurarti che provengano da una fonte attendibile. A seconda del messaggio ricevuto, esegui le azioni necessarie: aggiorna l'interfaccia utente, elabora il carrello, ecc. La convalida di origin è fondamentale per la sicurezza: impedisce agli script non autorizzati di interagire con la tua applicazione.

Una volta completata la personalizzazione, visualizza il progetto finale utilizzando l'URL di anteprima di seguito. Questo URL restituisce un'immagine del prodotto personalizzato, adatta come valore src in un tag <img>. Ideale per mostrare il prodotto personalizzato nel carrello, nel riepilogo dell'ordine o in qualsiasi punto dell'interfaccia del negozio.

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

Sostituisci {CART_ITEM_KEY} con la chiave effettiva dell'articolo del carrello e {APPLICATION_KEY} con la chiave dell'applicazione valida.

Esempio di utilizzo in un tag immagine:

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

I webhook vengono utilizzati da Fabrixa per notificare al tuo sistema eventi in tempo reale: aggiornamenti o creazioni di ordini. Quando si verifica un evento, Fabrixa invia un webhook al tuo server contenente le informazioni rilevanti. Il tuo server deve esporre un endpoint POST pubblico per gestire i webhook in entrata.

La richiesta webhook include i seguenti header per aiutarti a identificare e validare la richiesta in ingresso:

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

Ripartizione dell'intestazione

• content-type: impostato sempre su application/json per i webhook.
• x-webhook-signature: la firma HMAC-SHA256 per la verifica della richiesta.
• x-webhook-topic: il tipo di evento o l'argomento del webhook. Ad esempio:
  • order.created: attivato quando viene creato un nuovo ordine.
  • order.updated: attivato quando un ordine esistente viene aggiornato.

I webhook vengono inviati con lo User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); se il tuo endpoint filtra il traffico automatizzato, consentilo. Per essere sicuro che una richiesta provenga da Fabrixa, verifica x-webhook-signature.

I webhook Fabrixa notificano al tuo sistema cambiamenti nello stato ordine o nell’attività. Ogni webhook è attivato da uno specifico valore x-webhook-topic. Topic attualmente supportati:

Un esempio del payload inviato con il webhook. Questo payload rappresenta un aggiornamento dell'ordine:

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

Una volta spedito l’ordine, shipments elenca ogni spedizione con il corriere (carrier), il metodo di spedizione (method), lo stato (status: pending, registered, collected, in transit, delivered, failed, returned o canceled) e il tracciamento: tracking_number e tracking_url, e lo stesso per ogni pacco in packages quando una spedizione ne ha più di uno. Ogni volta che lo stato o il tracciamento di una spedizione cambia viene inviato un webhook order.updated, e GET /orders/{order_id} restituisce lo stesso campo.

Per assicurarti che la richiesta webhook sia autentica e non alterata, verifica l’header x-webhook-signature. Ricalcola la signature HMAC-SHA256 usando il raw request payload e la tua secret key, quindi confrontala con la signature ricevuta.

Esempio PHP grezzo

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

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

Sostituisci $yourSecret con la tua chiave segreta condivisa. Utilizza sempre hash_equals per confrontare le firme per mitigare gli attacchi temporali.

Per impostazione predefinita, i webhook vengono disabilitati dopo 10 tentativi di consegna non riusciti. Se l'endpoint restituisce uno stato non riuscito, ad esempio 404 o qualsiasi errore 5xx, il webhook riproverà per un totale di 10 volte. Se continua a restituire un codice di risposta non 2xx o non 3xx, verrà disattivato. Le risposte riuscite includono:

• 2xx - indica l'elaborazione riuscita, ad es. 200 OK.
• 301 e 302: risposte di reindirizzamento che indicano che il webhook è stato gestito o inoltrato con successo.

Ti consigliamo vivamente che il tuo endpoint restituisca un codice di stato 200 OK il più rapidamente possibile per confermare la corretta ricezione del webhook. Sebbene qualsiasi risposta 2xx o 3xx sia considerata riuscita, 200 è quella più comunemente utilizzata e affidabile.

Per evitare timeout o nuovi tentativi di consegna, restituire 200 OK immediatamente e gestire l'elaborazione del payload del webhook in modo asincrono, ad esempio tramite un processo in background o una coda. Se l'endpoint impiega troppo tempo per rispondere, potrebbe essere considerato un errore anche se alla fine la risposta ha esito positivo.

Le risposte con codici di stato nell'intervallo 4xx o 5xx o timeout attiveranno nuovi tentativi in ​​base al meccanismo di nuovo tentativo.