Fabrixa Integration API dokumentācija

Lai piekļūtu Integration API, autentificējiet savus pieprasījumus gan ar lietotnes piekļuves pilnvaru (access token), gan ar lietotnes atslēgu:

Authorization galvene

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Lietotnes atslēgas galvene

X-Application-Key: APPLICATION_KEY

cURL komandas piemērs

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'

Aizstājiet APPLICATION_ACCESS_TOKEN ar savu faktisko piekļuves pilnvaru un APPLICATION_KEY ar savu faktisko lietotnes atslēgu.

Integration API galapunkti ir sakārtoti pēc resursa veida un atbilst REST arhitektūras stilam. Katrs galapunkts pārstāv resursu, un darbības ar šiem resursiem tiek veiktas, izmantojot standarta HTTP metodes.

Visi Integration API pieprasījumi un atbildes ir JSON formātā, nodrošinot konsekventu un viegli lietojamu saskarni darbam ar API.

Pilnu informāciju par katru galapunktu, tostarp pieprasījumu un atbilžu piemērus, skatiet mūsu Swagger dokumentācijā.

Atbildes formāts

Visi galapunkti atgriež datus standartizētā formātā ar šādiem objektiem:

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

Atbildes objektu apraksts

Visi API pieprasījumi atgriež HTTP statusa kodus, kas sniedz ieskatu atbildē.

Kļūdas atbildes ķermenis

Kļūdas atbildes ķermeņa piemērs:

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

errors satur informāciju par to, kas neizdevās. Masīvs messages uzskaita kļūdu aprakstus. Bad Request gadījumā jūs saņemsiet to lauku nosaukumus, kuri neizturēja validāciju.

Integration API atbalsta ierobežojumu 30 pieprasījumi vienai lietotnei minūtē.

Ja pārsniegsiet šo ierobežojumu, saņemsiet atbildi 429 Too Many Requests.

Visas Integration API atbildes ietver galveni X-RateLimit-Remaining, kas norāda, cik pieprasījumus klients vēl var veikt, un galveni X-RateLimit-Limit, kas norāda kopējo minūtē pieļaujamo skaitu.

Izveidojiet Fabrixa pasūtījumus no sava veikala vai platformas, pievienojiet nepieciešamos apdrukas failus un sekojiet katrai vienībai, tai virzoties caur izpildi.

Lai izveidotu pasūtījumu, izmantojot Fabrixa Integration API, nosūtiet POST pieprasījumu uz https://api.fabrixa.com/v2/integration/orders. Pieprasījuma ķermenī jāiekļauj:

Pieprasījuma ķermeņa struktūra

Pieprasījuma piemērs

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

Lai iegūtu konkrēta pasūtījuma izpildes statusu, nosūtiet GET pieprasījumu uz https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Atbilde sniedz ar pasūtījumu saistīto izpilžu sarakstu, tostarp katras vienības statusu, produkta informāciju un ražošanas soļu gaitu.

Atbildes piemērs

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

Atbilde ietver izpilžu sarakstu, un katra no tām sniedz:

Katrs izpildes ieraksts atbilst konkrētam produktam vai produkta variantam pasūtījumā, un katram produkta eksemplāram pasūtījumā ir savs izpildes ieraksts - katra vienība ražošanas laikā tiek izsekota atsevišķi.

Ja pasūtījumam netiek atgriezta neviena izpilde, pasūtījums vēl nav nonācis apstrādes posmā.

Pievienojot pasūtījumam avota failus, pārliecinieties, ka tie atbilst šādām prasībām:

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

PDF prasības un lappušu secība

Lappušu secība PDF failā ir svarīga. Lappuses tiek piekārtotas produkta slāņiem pēc pozīcijas, un gaidītā lappušu secība atkarīga no produkta veida. Pārliecinieties, ka jūsu PDF lappuses atbilst pareizajai iesniedzamā produkta slāņu secībai.

Svarīgi: katrai PDF lappusei jāatbilst tās produkta slānim noteiktajiem izmēriem un jābūt pareizi orientētai. Izvietojiet dizainu tā, lai tā augšpuse sakristu ar lappuses augšpusi. Nepareizs lappuses izmērs vai orientācija ražošanā var radīt mērogošanas, pagriešanas vai izlīdzināšanas problēmas.

Fabrixa Studio ir rīks, kas ļauj lietotājiem reāllaikā ērti pielāgot un personalizēt produktus intuitīvā saskarnē, kurā viņi var izveidot vai augšupielādēt savus dizainus.

Fabrixa Studio ir lieliski piemērots uzņēmumiem, kas piedāvā pielāgotus produktus - klienti var redzēt savu dizainu vēl pirms pasūtījuma noformēšanas.

Fabrixa Studio varat iegult savā vietnē, izmantojot iframe. Tas ļauj klientiem personalizēt produktus tieši jūsu vietnē pirkuma noformēšanas laikā.

Iframe piemērs Fabrixa Studio iegulšanai:

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

Aizstājiet vērtības product_sku, cart_item_key un application_key ar savām dinamiskajām vērtībām.

• application_key - unikāla atslēga autentifikācijai Integration API.
• product_sku - produkta varianta SKU, kas iegūts no Integration API.
• cart_item_key - unikāla vērtība no iegulšanas platformas, kas identificē ar produktu saistīto groza vienību. To izmanto, lai saglabātu lietotāja pielāgojumus; pasūtījuma izveides laikā tā identificē saglabātos pielāgojumus un piesaista tos pasūtījumam. Skatiet piemēru zemāk.

Pasūtījuma izveides pieprasījums ar 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": {
    "...": "..."
  }
}

Kad iframe iekšpusē tiek nospiesta poga Pievienot grozam, tiek izpildīta šāda komanda:

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

Tāpat, kad tiek nospiesta poga Atpakaļ:

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

Metode postMessage nodrošina saziņu starp iframe un tā vecāklogu ar atšķirīgu izcelsmi, ļaujot informēt vecāklogu par konkrētām lietotāja darbībām.

Pirmais postMessage arguments ir dati, kurus vēlaties nosūtīt. Virkne 'customizationFinished' norāda, ka lietotājs ir pabeidzis pielāgošanu un pievieno produktu grozam. 'closeButtonClicked' norāda, ka lietotājs ir izvēlējies atgriezties.

Vecāklogā klausieties šos ziņojumus, izmantojot message notikuma klausītāju:

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

Vienmēr pārbaudiet ienākošo ziņojumu origin, lai pārliecinātos, ka tie nāk no uzticama avota. Atkarībā no saņemtā ziņojuma veiciet nepieciešamās darbības - atjauniniet lietotāja saskarni, apstrādājiet grozu un tā tālāk. origin validācija ir būtiska drošībai - tā neļauj nesankcionētiem skriptiem mijiedarboties ar jūsu lietotni.

Kad pielāgošana ir pabeigta, parādiet galīgo dizainu, izmantojot zemāk norādīto priekšskatījuma URL. Šis URL atgriež pielāgotā produkta attēlu, kas piemērots kā src vērtība <img> tagā. Ideāli piemērots pielāgotā produkta rādīšanai grozā, pasūtījuma kopsavilkumā vai jebkur citur jūsu veikala saskarnē.

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

Aizstājiet {CART_ITEM_KEY} ar faktisko groza vienības atslēgu un {APPLICATION_KEY} ar savu derīgo lietotnes atslēgu.

Lietojuma piemērs attēla tagā:

<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 izmanto tīmekļa āķus, lai reāllaikā informētu jūsu sistēmu par notikumiem - pasūtījumu atjauninājumiem vai izveidi. Kad notikums iestājas, Fabrixa nosūta uz jūsu serveri tīmekļa āķi ar attiecīgo informāciju. Jūsu serverim jānodrošina publisks POST galapunkts, kas apstrādā ienākošos tīmekļa āķus.

Tīmekļa āķa pieprasījums ietver šādas galvenes, kas palīdz identificēt un validēt ienākošo pieprasījumu:

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

Galveņu skaidrojums

• content-type - tīmekļa āķiem vienmēr application/json.
• x-webhook-signature - HMAC-SHA256 paraksts pieprasījuma pārbaudei.
• x-webhook-topic - tīmekļa āķa notikuma veids vai tēma. Piemēram:
  • order.created - tiek izraisīts, kad izveidots jauns pasūtījums.
  • order.updated - tiek izraisīts, kad atjaunināts esošs pasūtījums.

Fabrixa tīmekļa āķi informē jūsu sistēmu par izmaiņām pasūtījuma statusā vai darbībās. Katru tīmekļa āķi izraisa konkrēta x-webhook-topic vērtība. Pašlaik atbalstītās tēmas:

Pasūtījuma statusi

• Completed - pasūtījums ir nosūtīts vai izņemts, un saņemšana ir apstiprināta. Digitāliem produktiem klients ir samaksājis un faili ir pieejami lejupielādei.
• Canceled - klients atcēla maksājumu; darījums netika pabeigts.
• On hold - pasūtījums ir uz laiku bloķēts.
• Imported - pasūtījums tika importēts platformā.

Izpildes statusi

• Unfulfilled - pasūtījums vēl nav sagatavots un nosūtīts.
• Partially fulfilled - dažas vienības ir apstrādātas vai nosūtītas, pārējās vēl gaida.
• Scheduled - pasūtījums ir ieplānots apstrādei.
• Rejected - izpildes pieprasījums ir noraidīts, bieži nederīgas pasūtījuma informācijas vai pieejamības trūkuma dēļ.
• Fulfilled - pasūtījums ir pilnībā apstrādāts un piegādāts vai padarīts pieejams klientam.

Piemērs datiem, kas tiek nosūtīti ar tīmekļa āķi. Šie dati atspoguļo pasūtījuma atjauninājumu:

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

Lai pārliecinātos, ka tīmekļa āķa pieprasījums ir autentisks un nav mainīts, pārbaudiet galveni x-webhook-signature. Tas nozīmē no jauna aprēķināt HMAC-SHA256 parakstu, izmantojot pieprasījuma neapstrādātos datus un savu slepeno atslēgu, un pēc tam salīdzināt to ar saņemto parakstu.

Tīra PHP piemērs

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

Laravel piemērs

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

Aizstājiet $yourSecret ar savu koplietoto slepeno atslēgu. Parakstu salīdzināšanai vienmēr izmantojiet hash_equals, lai mazinātu laika mērīšanas uzbrukumu risku.

Pēc noklusējuma tīmekļa āķi tiek atspējoti pēc 10 neveiksmīgiem piegādes mēģinājumiem. Ja jūsu galapunkts atgriež neveiksmīgu statusu, piemēram, 404 vai jebkuru 5xx kļūdu, tīmekļa āķis tiks mēģināts nosūtīt kopumā 10 reizes. Ja tas turpinās atgriezt atbildes kodu, kas nav 2xx vai 3xx, tas tiks deaktivizēts. Par veiksmīgām atbildēm uzskata:

• 2xx - norāda uz veiksmīgu apstrādi, piemēram, 200 OK.
• 301 un 302 - pāradresācijas atbildes, kas norāda, ka tīmekļa āķis ir veiksmīgi apstrādāts vai pārsūtīts.

Mēs stingri iesakām, lai jūsu galapunkts pēc iespējas ātrāk atgrieztu statusa kodu 200 OK, apliecinot tīmekļa āķa veiksmīgu saņemšanu. Lai gan par veiksmīgu tiek uzskatīta jebkura 2xx vai 3xx atbilde, 200 ir visbiežāk lietotā un uzticamākā.

Lai izvairītos no piegādes noildzēm vai atkārtotiem mēģinājumiem, nekavējoties atgrieziet 200 OK un tīmekļa āķa datus apstrādājiet asinhroni, piemēram, ar fona uzdevumu vai rindu. Ja jūsu galapunkta atbilde aizņem pārāk ilgu laiku, to var uzskatīt par neveiksmi pat tad, ja atbilde galu galā ir veiksmīga.

Atbildes ar statusa kodiem 4xx vai 5xx diapazonā, kā arī noildzes izraisa atkārtotus mēģinājumus atbilstoši atkārtošanas mehānismam.