Päästäksesi integraatiosovellusliittymään, todenna pyyntösi käyttämällä sekä Application Access Token-tunnusta että Application Key:

Valtuutusotsikko

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Sovellusavaimen otsikko

X-Application-Key: APPLICATION_KEY

Esimerkki cURL-komento

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'

Korvaa APPLICATION_ACCESS_TOKEN todellisella käyttötunnuksellasi ja APPLICATION_KEY todellisella sovellusavaimellasi.

Integration API -päätepisteet on järjestetty resurssityypin mukaan ja noudattavat RESTful-arkkitehtuurityyliä. Jokainen päätepiste edustaa resurssia, ja näiden resurssien toiminnot suoritetaan tavallisilla HTTP-menetelmillä.

Kaikki Integration API -pyynnöt ja vastaukset ovat JSON-muodossa, mikä tarjoaa johdonmukaisen ja helppokäyttöisen käyttöliittymän vuorovaikutukseen API:n kanssa.

Katso täydelliset tiedot jokaisesta endpointista, mukaan lukien pyyntö- ja vastausesimerkit, Swagger-dokumentaatiosta.

Vastausmuoto

Kaikki päätepisteet palauttavat tiedot standardoidussa muodossa seuraavien objektien kanssa:

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

Vastausobjektien kuvaus

Kaikki API-pyynnöt palauttavat HTTP-tilakoodit, jotka antavat käsityksen vastauksesta.

Error Response Body

Esimerkki virhevastauksen rungosta:

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

errors sisältää tietoja siitä, mikä epäonnistui. messages-taulukko sisältää virhekuvaukset. Jos pyyntö on huono, saat niiden kenttien nimet, joiden vahvistus epäonnistui.

Integration API tukee enintään 30 pyyntöä sovellusta kohti minuutissa.

Jos ylität tämän rajan, saat 429 Too Many Requests-vastauksen.

Kaikki Integration API -vastaukset sisältävät X-RateLimit-Remaining-otsikon, kuinka monta pyyntöä asiakas voi vielä tehdä, ja X-RateLimit-Limit-otsikon, joka on sallittu kokonaismäärä minuutissa.

Luo tilauksia Fabrixassa omalta myymälältäsi tai alustaltasi, liitä tarvittavat tulostustiedostot ja seuraa jokaista tuotetta sen eteneessä.

Luo tilaus Fabrixa Integration API:n kautta lähettämällä POST-pyyntö osoitteeseen https://api.fabrixa.com/v2/integration/orders. Pyyntöelimen tulee sisältää:

Pyydä kehon rakennetta

Esimerkkipyyntö

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

Saat tietyn tilauksen toteutustilan lähettämällä GET-pyynnön numeroon https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Vastauksessa on luettelo tilaukseen liittyvistä toimituksista, mukaan lukien kunkin tuotteen tila, tuotetiedot ja tuotantovaiheen edistyminen.

Esimerkkivastaus

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

Vastaus sisältää luettelon suorituksista, joista jokainen sisältää:

Jokainen toimitustietue vastaa tiettyä tuotetta tai tuoteversiota tilauksen sisällä, ja jokaisella tilauksen tuotteen kopiolla on oma toimitustietue – jokaista tuotetta seurataan yksitellen koko tuotannon ajan.

Jos tilaukselle ei palauteta toimituksia, tilaus ei ole vielä siirtynyt käsittelyvaiheeseen.

Kun sisällytät lähdetiedostoja tilaukseesi, varmista, että ne täyttävät seuraavat vaatimukset:

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

PDF-vaatimukset ja sivujärjestys

PDF:n sivujen järjestys on tärkeä. Sivut kohdistetaan tuotetasoihin sijainnin mukaan, ja odotettu sivujärjestys riippuu tuotetyypistä. Varmista, että PDF-tiedoston sivut noudattavat lähettämäsi tuotteen oikeaa kerrosjärjestystä.

Tärkeää: jokaisen PDF-sivun on vastattava tuotekerroksen vaadittuja mittoja ja oltava oikein suunnattu. Aseta taide niin, että kuvion yläreuna on kohdakkain sivun yläosan kanssa. Virheellinen sivun koko tai suunta voi aiheuttaa skaalaus-, kierto- tai kohdistusongelmia tuotannossa.

Fabrixa Studio on työkalu, jonka avulla käyttäjät voivat räätälöidä ja personoida tuotteita saumattomasti reaaliajassa intuitiivisen käyttöliittymän avulla, jossa käyttäjät voivat luoda tai lähettää omia mallejaan.

Fabrixa Studio on ihanteellinen yrityksille, jotka tarjoavat räätälöityjä tuotteita - mahdollistaen asiakkaiden visualisoinnin suunnittelussa ennen tilausten viimeistelyä.

Voit upottaa Fabrixa Studion verkkosivustollesi käyttämällä iframe-komentoa. Näin asiakkaasi voivat muokata tuotteita suoraan sivustollasi kassalla.

Esimerkki iframe-kehyksestä Fabrixa Studion upottamista varten:

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

Korvaa product_sku-, cart_item_key- ja application_key-arvot dynaamisilla arvoillasi.

• application_key - yksilöllinen avain Integration API -todennusta varten.
• product_sku - tuotevariantin SKU, joka haetaan Integration API:sta.
• cart_item_key - upottavan alustan yksilöllinen arvo, joka tunnistaa tuotteeseen liittyvän ostoskoririvin. Sitä käytetään käyttäjän mukautusten tallentamiseen; tilausta luotaessa se tunnistaa tallennetut mukautukset ja liittää ne tilaukseen. Katso esimerkki alta.

Pyydä luomaan tilaus 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": {
    "...": "..."
  }
}

Kun Lisää ostoskoriin -painiketta napsautetaan iframe-kehyksen sisällä, seuraava komento suoritetaan:

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

Vastaavasti, kun Takaisin-painiketta napsautetaan:

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

postMessage-menetelmä helpottaa lähteiden välistä viestintää iframe-kehyksen ja sen ylätason ikkunan välillä, jolloin se voi ilmoittaa ylätason käyttäjälle tietyistä käyttäjän toimista.

Ensimmäinen argumentti postMessage on tiedot, jotka haluat lähettää. Merkkijono 'customizationFinished' osoittaa, että käyttäjä on viimeistellyt mukauttamisen ja lisää tuotteen ostoskoriin. 'closeButtonClicked' osoittaa, että käyttäjä on päättänyt palata takaisin.

Kuuntele ylätason ikkunassa näitä viestejä käyttämällä message-tapahtuman kuuntelua:

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

Tarkista aina saapuvien viestien origin varmistaaksesi, että ne tulevat luotettavasta lähteestä. Riippuen vastaanotetusta viestistä, suorita tarvittavat toimenpiteet - päivitä käyttöliittymä, käsittele ostoskori jne. origin-tarkistus on erittäin tärkeää turvallisuuden kannalta - se estää luvattomia komentosarjoja vuorovaikutuksessa sovelluksesi kanssa.

Kun mukauttaminen on valmis, näytä lopullinen malli käyttämällä alla olevaa esikatselu-URL-osoitetta. Tämä URL-osoite palauttaa kuvan mukautetusta tuotteesta, joka sopii src-arvoksi <img>-tunnisteessa. Ihanteellinen mukautetun tuotteen näyttämiseen ostoskorissasi, tilausyhteenvedossa tai missä tahansa myymäläsi käyttöliittymässä.

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

Korvaa {CART_ITEM_KEY} todellisella ostoskorin nimikeavaimella ja {APPLICATION_KEY} voimassa olevalla sovellusavaimellasi.

Esimerkki käytöstä kuvatunnisteessa:

<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 käyttää Webhookeja ilmoittamaan järjestelmällesi reaaliaikaisista tapahtumista – tilauspäivityksistä tai luomuksista. Kun tapahtuma tapahtuu, Fabrixa lähettää palvelimellesi webhookin, joka sisältää tarvittavat tiedot. Palvelimesi on esitettävä julkinen POST-päätepiste saapuvien webhookien käsittelemiseksi.

Webhook-pyyntö sisältää seuraavat otsikot, jotka auttavat sinua tunnistamaan ja vahvistamaan saapuvan pyynnön:

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

Otsikkojen erittely

• content-type - aina application/json webhooks-pyynnöissä.
• x-webhook-signature - HMAC-SHA256-allekirjoitus pyynnön varmistusta varten.
• x-webhook-topic - webhookin tapahtumatyyppi tai aihe. Esimerkiksi:
  • order.created - käynnistyy, kun uusi tilaus luodaan.
  • order.updated - käynnistyy, kun olemassa oleva tilaus päivitetään.

Fabrixa webhookit ilmoittavat järjestelmällesi tilauksen tilan tai toiminnan muutoksista. Jokainen webhook käynnistyy tietyllä x-webhook-topic-arvolla. Tällä hetkellä tuetut aiheet:

Tilauksen tilat

• Valmis - tilaus on lähetetty tai noudettu ja vastaanotto on vahvistettu. Digitaalisista tuotteista asiakas on maksanut ja tiedostot ovat ladattavissa.
• Peruutettu - asiakas peruutti maksun; tapahtumaa ei suoritettu loppuun.
• Pidossa - tilaus on tilapäisesti estetty.
• Tuodu - tilaus tuotiin tilaukseen alusta.

Toteutustilat

• Toteuttamaton - tilausta ei ole vielä valmistettu tai lähetetty.
• Osittain täytetty - jotkut tuotteet on vielä käsitelty tai lähetetty vireillä.
• Scheduled - tilaus on suunniteltu ja ajoitettu käsiteltäväksi.
• Hylätty - tilauksen yksityiskohdat hylätty, tai tilauksen toimituspyyntö on usein virheellinen ei saatavilla.
• Fulfilled - tilaus on käsitelty kokonaan ja toimitettu tai asetettu asiakkaan saataville.

Esimerkki webhookin mukana lähetetystä hyötykuormasta. Tämä hyötykuorma edustaa tilauspäivitystä:

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

Varmista x-webhook-signature-otsikko varmistaaksesi, että webhook-pyyntö on aito ja vahingoittumaton. Tämä tarkoittaa, että HMAC-SHA256-allekirjoitus lasketaan uudelleen raakapyynnön hyötykuorman ja salaisen avaimen avulla, minkä jälkeen sitä verrataan vastaanotettuun allekirjoitukseen.

Raaka PHP esimerkki

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

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

Korvaa $yourSecret jaetulla salaisella avaimellasi. Käytä aina hash_equals allekirjoitusten vertaamiseen ajoitushyökkäysten vähentämiseksi.

Webhookit poistetaan oletusarvoisesti käytöstä 10 epäonnistuneen toimitusyrityksen jälkeen. Jos päätepisteesi palauttaa epäonnistuneen tilan, kuten 404 tai minkä tahansa 5xx-virheen, webhook yrittää uudelleen yhteensä 10 kertaa. Jos se jatkaa ei-2xx- tai ei-3xx-vastauskoodin palauttamista, se poistetaan käytöstä. Onnistuneita vastauksia ovat mm.

• 2xx - osoittaa onnistuneen käsittelyn, esim. 200 OK.
• 301 ja 302 - uudelleenohjausvastaukset, jotka osoittavat, että webhook on käsitelty tai lähetetty onnistuneesti.

Suosittelemme, että päätepiste palauttaa 200 OK-tilakoodin mahdollisimman nopeasti vahvistaakseen webhookin onnistuneen vastaanottamisen. Vaikka mitä tahansa 2xx tai 3xx vastausta pidetään onnistuneena, 200 on yleisimmin käytetty ja luotettavin.

Toimituksen aikakatkaisujen tai uudelleenyritysten välttämiseksi palauta 200 OK välittömästi ja käsittele webhook-hyötykuorman käsittelyä asynkronisesti, esimerkiksi taustatyön tai jonon kautta. Jos päätepisteesi vastaaminen kestää liian kauan, sitä voidaan pitää epäonnistuneena, vaikka vastaus olisi lopulta onnistunut.

Vastaukset, joiden tilakoodit ovat alueella 4xx tai 5xx, tai aikakatkaisut, käynnistävät uudelleenyritykset uudelleenyritysmekanismin mukaisesti.