Fabrixa Integration API dokumentatsioon

Integration API-le ligipääsuks autendi oma päringud nii rakenduse ligipääsuvõtme (access token) kui ka rakenduse võtmega:

Authorization-päis

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Rakenduse võtme päis

X-Application-Key: APPLICATION_KEY

cURL-käsu näidis

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'

Asenda APPLICATION_ACCESS_TOKEN oma tegeliku ligipääsuvõtmega ja APPLICATION_KEY oma tegeliku rakenduse võtmega.

Integration API lõpp-punktid on korraldatud ressursitüübi järgi ja järgivad REST-arhitektuuri stiili. Iga lõpp-punkt esindab ressurssi ning toiminguid nende ressurssidega tehakse tavapäraste HTTP-meetoditega.

Kõik Integration API päringud ja vastused on JSON-vormingus, mis annab API-ga suhtlemiseks ühtse ja hõlpsasti kasutatava liidese.

Iga lõpp-punkti täielikud üksikasjad koos päringu- ja vastusenäidetega leiad meie Swaggeri dokumentatsioonist.

Vastuse vorming

Kõik lõpp-punktid tagastavad andmed ühtses vormingus järgmiste objektidega:

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

Vastuse objektide kirjeldus

Kõik API päringud tagastavad HTTP olekukoodid, mis annavad vastuse kohta selgust.

Veavastuse keha

Veavastuse keha näidis:

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

errors sisaldab üksikasju selle kohta, mis ebaõnnestus. Massiiv messages loetleb vigade kirjeldused. Bad Requesti korral saad nende väljade nimed, mis valideerimise läbi ei teinud.

Integration API toetab piirangut 30 päringut rakenduse kohta minutis.

Selle piirangu ületamisel saad vastuse 429 Too Many Requests.

Kõik Integration API vastused sisaldavad päist X-RateLimit-Remaining, mis näitab, mitu päringut klient veel teha saab, ning päist X-RateLimit-Limit, mis näitab minutis lubatud koguarvu.

Loo Fabrixas tellimusi oma poest või platvormilt, lisa nõutud trükifailid ja jälgi iga üksust, kui see läbib täitmise etapid.

Tellimuse loomiseks Fabrixa Integration API kaudu saada POST-päring aadressile https://api.fabrixa.com/v2/integration/orders. Päringu keha peab sisaldama:

Päringu keha struktuur

Päringu näidis

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

Konkreetse tellimuse täitmise oleku saamiseks saada GET-päring aadressile https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Vastus annab tellimusega seotud täitmiste loendi koos iga üksuse olekuga, tooteandmetega ja tootmisetappide edenemisega.

Vastuse näidis

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

Vastus sisaldab täitmiste loendit, kus iga kirje annab:

Iga täitmiskirje vastab tellimuse konkreetsele tootele või toote variandile ning igal tellimuses oleval tooteeksemplaril on oma täitmiskirje - iga üksust jälgitakse kogu tootmise vältel eraldi.

Kui tellimuse kohta täitmisi ei tagastata, ei ole tellimus veel töötlemisetappi jõudnud.

Kui lisad tellimusele lähtefaile, veendu, et need vastaksid järgmistele nõuetele:

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

PDF-i nõuded ja lehekülgede järjekord

Lehekülgede järjekord PDF-is on oluline. Leheküljed seotakse tootekihtidega asukoha järgi ja oodatav lehekülgede järjekord sõltub tootetüübist. Veendu, et sinu PDF-i leheküljed järgiksid esitatava toote õiget kihijärjestust.

Oluline: iga PDF-lehekülg peab vastama oma tootekihi nõutud mõõtmetele ja olema õigesti suunatud. Paiguta kujundus nii, et selle ülaosa jääks lehekülje ülaossa. Vale leheküljesuurus või -suund võib tootmises põhjustada mastaapimise, pööramise või joondamise probleeme.

Fabrixa Studio on tööriist, mis laseb kasutajatel tooteid reaalajas sujuvalt kohandada ja isikupärastada intuitiivses liideses, kus nad saavad oma kujundusi luua või üles laadida.

Fabrixa Studio sobib ideaalselt ettevõtetele, kes pakuvad eritellimustooteid - kliendid näevad oma kujundust juba enne tellimuse vormistamist.

Fabrixa Studio saad oma veebisaidile manustada iframe-i abil. Nii saavad kliendid tooteid ostu ajal otse sinu saidil isikupärastada.

Fabrixa Studio manustamise iframe-i näidis:

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

Asenda väärtused product_sku, cart_item_key ja application_key oma dünaamiliste väärtustega.

• application_key - unikaalne võti Integration API-s autentimiseks.
• product_sku - toote variandi SKU, mis on saadud Integration API-st.
• cart_item_key - manustavalt platvormilt pärit unikaalne väärtus, mis tuvastab tootega seotud ostukorvi üksuse. Seda kasutatakse kasutaja kohanduste salvestamiseks; tellimuse loomisel tuvastab see salvestatud kohandused ja seob need tellimusega. Vaata näidet allpool.

Päring tellimuse loomiseks väljaga 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": {
    "...": "..."
  }
}

Kui iframe-i sees klõpsatakse nuppu Lisa ostukorvi, käivitatakse järgmine käsk:

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

Sarnaselt siis, kui klõpsatakse nuppu Tagasi:

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

Meetod postMessage võimaldab iframe-i ja selle vanemakna vahelist eri päritolu suhtlust, nii saab see vanemakent konkreetsetest kasutaja tegevustest teavitada.

Meetodi postMessage esimene argument on andmed, mida soovid saata. Sõne 'customizationFinished' tähendab, et kasutaja on kohandamise lõpetanud ja lisab toote ostukorvi. 'closeButtonClicked' tähendab, et kasutaja valis tagasi mineku.

Vanemaknas kuula neid sõnumeid message-sündmuse kuulajaga:

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

Kontrolli alati sissetulevate sõnumite origin-i, et need tuleksid usaldusväärsest allikast. Sõltuvalt saadud sõnumist tee vajalikud toimingud - uuenda kasutajaliidest, töötle ostukorvi ja nii edasi. origin-i valideerimine on turvalisuse jaoks hädavajalik - see takistab volitamata skriptidel sinu rakendusega suhelda.

Kui kohandamine on lõpetatud, kuva lõplik kujundus allpool oleva eelvaate URL-iga. See URL tagastab kohandatud toote pildi, mis sobib src-väärtuseks <img>-sildis. Ideaalne kohandatud toote näitamiseks ostukorvis, tellimuse kokkuvõttes või mujal sinu poe liideses.

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

Asenda {CART_ITEM_KEY} tegeliku ostukorvi üksuse võtmega ja {APPLICATION_KEY} oma kehtiva rakenduse võtmega.

Kasutusnäidis pildisildis:

<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 kasutab veebihooke, et teavitada sinu süsteemi reaalajas toimuvatest sündmustest - tellimuste uuendustest või loomisest. Kui sündmus toimub, saadab Fabrixa sinu serverisse veebihooki koos asjakohase teabega. Sinu server peab avama avaliku POST-lõpp-punkti, mis sissetulevaid veebihooke käsitleb.

Veebihooki päring sisaldab järgmisi päiseid, mis aitavad sul sissetuleva päringu tuvastada ja kontrollida:

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

Päiste ülevaade

• content-type - veebihookide puhul alati application/json.
• x-webhook-signature - HMAC-SHA256 allkiri päringu kontrollimiseks.
• x-webhook-topic - veebihooki sündmuse tüüp või teema. Näiteks:
  • order.created - käivitub uue tellimuse loomisel.
  • order.updated - käivitub olemasoleva tellimuse uuendamisel.

Fabrixa veebihookid teavitavad sinu süsteemi tellimuse oleku või tegevuse muutustest. Iga veebihooki käivitab kindel x-webhook-topic väärtus. Praegu toetatud teemad:

Tellimuse olekud

• Completed - tellimus on saadetud või kätte saadud ja kättesaamine on kinnitatud. Digitaalsete toodete puhul on klient maksnud ja failid on allalaadimiseks saadaval.
• Canceled - klient tühistas makse; tehing jäi lõpetamata.
• On hold - tellimus on ajutiselt peatatud.
• Imported - tellimus imporditi platvormile.

Täitmise olekud

• Unfulfilled - tellimust pole veel ette valmistatud ega välja saadetud.
• Partially fulfilled - osa üksusi on töödeldud või saadetud, ülejäänud ootavad.
• Scheduled - tellimus on töötlemiseks planeeritud ja ajastatud.
• Rejected - täitmistaotlus on tagasi lükatud, sageli vigaste tellimuse andmete või kättesaamatuse tõttu.
• Fulfilled - tellimus on täielikult töödeldud ning kliendile tarnitud või kättesaadavaks tehtud.

Näidis andmetest, mis veebihookiga saadetakse. Need andmed kajastavad tellimuse uuendust:

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

Et veenduda, et veebihooki päring on autentne ja muutmata, kontrolli päist x-webhook-signature. Selleks arvuta HMAC-SHA256 allkiri päringu töötlemata andmete ja oma salajase võtme põhjal uuesti ning võrdle seda saadud allkirjaga.

Puhta PHP näide

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

Laraveli näide

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

Asenda $yourSecret oma jagatud salajase võtmega. Kasuta allkirjade võrdlemiseks alati hash_equals, et vähendada ajastusrünnakute ohtu.

Veebihookid lülitatakse vaikimisi välja pärast 10 ebaõnnestunud edastuskatset. Kui sinu lõpp-punkt tagastab ebaõnnestumise oleku, näiteks 404 või mis tahes 5xx vea, korratakse veebihooki kokku 10 korda. Kui see tagastab jätkuvalt vastusekoodi, mis ei ole 2xx ega 3xx, lülitatakse see välja. Õnnestunud vastused on:

• 2xx - näitab edukat töötlemist, nt 200 OK.
• 301 ja 302 - ümbersuunamisvastused, mis näitavad, et veebihook on edukalt käsitletud või edasi suunatud.

Soovitame tungivalt, et sinu lõpp-punkt tagastaks veebihooki kättesaamise kinnitamiseks olekukoodi 200 OK võimalikult kiiresti. Kuigi õnnestunuks loetakse iga 2xx või 3xx vastus, on 200 kõige levinum ja usaldusväärsem.

Edastuse ajalõpu või kordamise vältimiseks tagasta kohe 200 OK ja töötle veebihooki andmeid asünkroonselt, näiteks taustatöö või järjekorra kaudu. Kui sinu lõpp-punkti vastus võtab liiga kaua aega, võib seda lugeda ebaõnnestumiseks, isegi kui vastus lõpuks õnnestub.

Vastused olekukoodidega vahemikus 4xx või 5xx ning ajalõpud käivitavad kordused vastavalt kordamismehhanismile.