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.

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": "0647185332"
  },
  "shipping_address": {
    "address": "Pierre cuypershof",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0647185332"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SYZXG1585577",
    "tracking_url": "https://postnl.nl/tracktrace/3SYZXG1585577",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

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.

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.

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",
  "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 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:

Stati degli ordini

• Completato: l'ordine è stato spedito o ritirato e la ricezione è confermata. Per i prodotti digitali, il cliente ha pagato e i file sono disponibili per il download.
• Annullato: pagamento annullato dal cliente; la transazione non è stata completata.
• In sospeso - l'ordine è temporaneamente bloccato.
• Importato - l'ordine è stato importato nella piattaforma.

Stati di adempimento

• Non evaso: l'ordine non è stato ancora preparato o inviato.
• Parzialmente evaso: alcuni articoli sono stati elaborati o spediti, altri sono ancora in sospeso.
• Programmati: l'ordine è pianificato e programmato per l'elaborazione.
• Rifiutato: la richiesta di evasione è stata rifiutata, spesso a causa di dettagli dell'ordine non validi o indisponibilità.
• Evaso: l'ordine è stato completamente elaborato e consegnato o reso disponibile al cliente.

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": "imported",
  "fulfillment_status": "unfulfilled",
  "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": "unfulfilled",
      "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"
          }
        }
      ]
    }
  ]
}

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.