Fabrixa Integration API dokumentáció

Az Integration API eléréséhez hitelesítse a kéréseit egy alkalmazás hozzáférési tokennel és egy alkalmazáskulccsal is:

Authorization fejléc

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Alkalmazáskulcs fejléc

X-Application-Key: APPLICATION_KEY

Példa cURL parancsra

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'

Cserélje az APPLICATION_ACCESS_TOKEN értéket a saját hozzáférési tokenjére, az APPLICATION_KEY értéket pedig a saját alkalmazáskulcsára.

Az Integration API végpontjai erőforrástípus szerint szerveződnek, és a REST architekturális stílust követik. Minden végpont egy erőforrást képvisel, és az erőforrásokon végzett műveletek a szokásos HTTP-metódusokkal történnek.

Az Integration API minden kérése és válasza JSON formátumú, így egységes és könnyen használható felületet nyújt az API-val való munkához.

Az egyes végpontok részletes leírását, kérés- és válaszpéldákkal együtt, a Swagger dokumentációnkban találja.

Válaszformátum

Minden végpont egységes formátumban ad vissza adatokat, a következő objektumokkal:

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

A válaszobjektumok leírása

Minden API-kérés HTTP állapotkódot ad vissza, amely tájékoztat a válaszról.

A hibaválasz törzse

Példa egy hibaválasz törzsére:

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

Az errors részletezi, mi hiúsult meg. A messages tömb a hibaleírásokat sorolja fel. Bad Request esetén megkapja azoknak a mezőknek a nevét, amelyek nem mentek át a validáción.

Az Integration API alkalmazásonként 30 kérés/perc korlátot támogat.

Ha túllépi ezt a korlátot, 429 Too Many Requests választ kap.

Az Integration API minden válasza tartalmazza az X-RateLimit-Remaining fejlécet, vagyis hogy a kliens még hány kérést tehet, és az X-RateLimit-Limit fejlécet, azaz a percenként engedélyezett teljes mennyiséget.

Hozzon létre megrendeléseket a Fabrixában a saját webáruházából vagy platformjáról, csatolja a szükséges nyomtatási fájlokat, és kövesse minden tételt, ahogy végighalad a teljesítésen.

Ha a Fabrixa Integration API-n keresztül szeretne megrendelést létrehozni, küldjön POST kérést a https://api.fabrixa.com/v2/integration/orders címre. A kérés törzsének tartalmaznia kell:

A kérés törzsének felépítése

Példakérés

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

Egy adott megrendelés teljesítési állapotáért küldjön GET kérést a https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments címre. A válasz felsorolja a megrendeléshez tartozó teljesítéseket, köztük az egyes tételek állapotát, a termékadatokat és a gyártási lépések előrehaladását.

Példaválasz

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

A válasz teljesítések listáját tartalmazza, amelyek mindegyike megadja:

Minden teljesítési rekord a megrendelés egy adott termékéhez vagy termékváltozatához tartozik, és a megrendelésben szereplő minden példánynak külön teljesítési rekordja van - minden tételt egyedileg követünk a gyártás során.

Ha egy megrendeléshez nem érkezik vissza teljesítés, a megrendelés még nem került feldolgozási szakaszba.

Ha forrásfájlokat csatol a megrendeléshez, ügyeljen rá, hogy megfeleljenek a következő követelményeknek:

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

PDF-követelmények és oldalsorrend

A PDF-ben az oldalak sorrendje fontos. Az oldalakat pozíció szerint feleltetjük meg a termékrétegeknek, és az elvárt oldalsorrend a terméktípustól függ. Ügyeljen rá, hogy a PDF oldalai a beadott termékhez tartozó helyes rétegsorrendet kövessék.

Fontos: minden PDF-oldalnak meg kell felelnie a saját termékrétegéhez tartozó méreteknek, és helyes tájolásúnak kell lennie. Úgy helyezze el a grafikát, hogy a dizájn teteje az oldal tetejéhez illeszkedjen. A hibás oldalméret vagy tájolás méretezési, elforgatási vagy illesztési problémákat okozhat a gyártásban.

A Fabrixa Studio olyan eszköz, amellyel a felhasználók valós időben, gördülékenyen szabhatják testre és személyesíthetik a termékeket egy intuitív felületen, ahol saját dizájnt hozhatnak létre vagy tölthetnek fel.

A Fabrixa Studio ideális az egyedi termékeket kínáló vállalkozásoknak - a vásárlók már a megrendelés véglegesítése előtt láthatják a dizájnjukat.

A Fabrixa Studio iframe segítségével beágyazható a webhelyére. Így a vásárlói a fizetési folyamat során közvetlenül az Ön oldalán személyesíthetik a termékeket.

Példa iframe a Fabrixa Studio beágyazásához:

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

Cserélje a product_sku, cart_item_key és application_key értékeket a saját dinamikus értékeire.

• application_key - egyedi kulcs az Integration API-hoz való hitelesítéshez.
• product_sku - a termékváltozat SKU-ja, az Integration API-ból lekérve.
• cart_item_key - a beágyazó platformról származó egyedi érték, amely a termékhez tartozó kosártételt azonosítja. A felhasználói testreszabások mentésére szolgál; a megrendelés létrehozásakor azonosítja a mentett testreszabásokat, és a megrendeléshez rendeli őket. Lásd az alábbi példát.

Megrendelés létrehozása cart_item_key értékkel

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

Amikor az iframe-en belül a Kosárba gombra kattintanak, a következő utasítás fut le:

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

Hasonlóképpen, amikor a Vissza gombra kattintanak:

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

A postMessage metódus teszi lehetővé az iframe és a szülőablak közötti, eltérő eredetű kommunikációt, így az értesítheti a szülőablakot bizonyos felhasználói műveletekről.

A postMessage első paramétere a küldeni kívánt adat. A 'customizationFinished' szöveg azt jelzi, hogy a felhasználó véglegesítette a testreszabást, és a kosárba teszi a terméket. A 'closeButtonClicked' azt jelzi, hogy a felhasználó a visszalépést választotta.

A szülőablakban a message eseményfigyelővel hallgassa ezeket az üzeneteket:

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

Mindig ellenőrizze a bejövő üzenetek origin értékét, hogy megbízható forrásból származnak-e. A kapott üzenettől függően hajtsa végre a szükséges műveleteket - a felület frissítését, a kosár feldolgozását és így tovább. Az origin validálása biztonsági szempontból létfontosságú - megakadályozza, hogy illetéktelen szkriptek kommunikáljanak az alkalmazásával.

A testreszabás befejezése után az alábbi előnézeti URL-lel jelenítse meg a végleges dizájnt. Ez az URL a testreszabott termék képét adja vissza, amely src értékként használható egy <img> elemben. Ideális a testreszabott termék megjelenítéséhez a kosárban, a megrendelés összegzésében vagy bárhol az üzlete felületén.

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

Cserélje a {CART_ITEM_KEY} értéket a tényleges kosártétel-kulcsra, a {APPLICATION_KEY} értéket pedig az érvényes alkalmazáskulcsára.

Példa a használatra képelemben:

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

A Fabrixa webhookokkal értesíti a rendszerét a valós időben történő eseményekről - megrendelések frissítéséről vagy létrehozásáról. Amikor egy esemény bekövetkezik, a Fabrixa webhookot küld a szerverére a vonatkozó információkkal. A szerverének nyilvános POST végpontot kell biztosítania a bejövő webhookok kezeléséhez.

A webhook kérés a következő fejléceket tartalmazza, amelyek segítenek a bejövő kérés azonosításában és ellenőrzésében:

{
  "content-type": "application/json",
  "x-webhook-signature": "YmEwNjBhMGMyMzE3ZWQ5NGQ5NDYwOGVhNzNhMjQ4M2MyODZkZmI3NTQ1YzYxYjdkMzNhZjgzYzBmMTkxYTAxMw==",
  "x-webhook-topic": "order.updated"
}

A fejlécek részletei

• content-type - webhookok esetén mindig application/json.
• x-webhook-signature - a kérés ellenőrzésére szolgáló HMAC-SHA256 aláírás.
• x-webhook-topic - a webhook eseménytípusa vagy témája. Például:
  • order.created - új megrendelés létrehozásakor indul.
  • order.updated - meglévő megrendelés frissítésekor indul.

A Fabrixa webhookjai értesítik a rendszerét a megrendelés állapotában vagy tevékenységében bekövetkező változásokról. Minden webhookot egy adott x-webhook-topic érték indít el. A jelenleg támogatott témák:

Megrendelési állapotok

• Completed - a megrendelést kiszállították vagy átvették, és az átvétel megerősítést nyert. Digitális termékek esetén a vásárló fizetett, és a fájlok letölthetők.
• Canceled - a vásárló megszakította a fizetést; a tranzakció nem fejeződött be.
• On hold - a megrendelés átmenetileg zárolva van.
• Imported - a megrendelést importáltuk a platformra.

Teljesítési állapotok

• Unfulfilled - a megrendelést még nem készítették elő és nem küldték ki.
• Partially fulfilled - néhány tétel feldolgozásra vagy kiszállításra került, a többi még várakozik.
• Scheduled - a megrendelés feldolgozása be van tervezve és ütemezve.
• Rejected - a teljesítési kérést elutasítottuk, jellemzően hibás megrendelési adatok vagy készlethiány miatt.
• Fulfilled - a megrendelés teljesen feldolgozásra került, és a vásárlóhoz eljutott vagy elérhetővé vált számára.

Példa a webhookkal küldött payloadra. Ez a payload egy megrendelés frissítését jelenti:

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

Ahhoz, hogy megbizonyosodjon róla, hogy a webhook kérés eredeti és nem módosították, ellenőrizze az x-webhook-signature fejlécet. Ehhez a kérés nyers payloadja és a titkos kulcsa alapján újra ki kell számolnia a HMAC-SHA256 aláírást, majd össze kell hasonlítania a kapott aláírással.

Példa tiszta PHP-ban

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

Példa Laravelben

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

Cserélje a $yourSecret értéket a megosztott titkos kulcsára. Az aláírások összehasonlításához mindig a hash_equals függvényt használja, hogy csökkentse az időzítéses támadások esélyét.

A webhookok alapértelmezés szerint 10 sikertelen küldési kísérlet után letiltásra kerülnek. Ha a végpontja sikertelen állapotot ad vissza, például 404 vagy bármilyen 5xx hibát, a webhook összesen 10 alkalommal próbálkozik újra. Ha továbbra is 2xx vagy 3xx körön kívüli válaszkódot ad vissza, a webhook deaktiválódik. Sikeresnek számítanak:

• 2xx - sikeres feldolgozást jelez, például 200 OK.
• 301 és 302 - átirányítási válaszok, amelyek azt jelzik, hogy a webhookot sikeresen kezelték vagy továbbították.

Erősen javasoljuk, hogy a végpontja mielőbb 200 OK állapotkódot adjon vissza, visszaigazolva a webhook sikeres fogadását. Bár minden 2xx vagy 3xx válasz sikeresnek számít, a 200 a leggyakoribb és legmegbízhatóbb.

A küldési időtúllépések és újrapróbálkozások elkerüléséhez azonnal adjon vissza 200 OK választ, a webhook payloadját pedig aszinkron módon dolgozza fel, például háttérfeladattal vagy várólistával. Ha a végpontja túl sokáig válaszol, a kísérlet sikertelennek minősülhet, még akkor is, ha a válasz végül sikeres.

A 4xx vagy 5xx tartományba eső állapotkóddal érkező válaszok, valamint az időtúllépések az újrapróbálkozási mechanizmus szerint újabb kísérleteket indítanak.