For at få adgang til Integration API skal du godkende dine anmodninger ved hjælp af både et Application Access Token og en Application Key:

Autorisationshoved

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Applikationsnøglehoved

X-Application-Key: APPLICATION_KEY

Eksempel på cURL-kommando

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'

Erstat APPLICATION_ACCESS_TOKEN med dit faktiske adgangstoken og APPLICATION_KEY med din faktiske applikationsnøgle.

Integration API-endepunkterne er organiseret efter ressourcetype og følger den RESTful-arkitektoniske stil. Hvert slutpunkt repræsenterer en ressource, og handlinger på disse ressourcer udføres ved hjælp af standard HTTP-metoder.

Alle Integration API-anmodninger og -svar er i JSON-format, hvilket giver en ensartet og brugervenlig grænseflade til interaktion med API'en.

For fulde detaljer om hvert endpoint, inklusive eksempler på requests og responses, se vores Swagger-dokumentation.

Svarformat

Alle endepunkter returnerer data i et standardiseret format med disse objekter:

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

Beskrivelse af svarobjekter

Alle API-anmodninger returnerer HTTP-statuskoder, der giver indsigt i svaret.

Error Response Body

Et eksempel på en fejlsvartekst:

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

errors indeholder detaljer om, hvad der fejlede. messages-arrayet viser fejlbeskrivelser. For en dårlig anmodning vil du modtage navnene på de felter, der mislykkedes ved validering.

Integrations-API'en understøtter en grænse på 30 anmodninger pr. applikation pr. minut.

Hvis du overskrider denne grænse, vil du modtage et 429 Too Many Requests svar.

Alle Integration API-svar inkluderer X-RateLimit-Remaining-headeren, hvor mange anmodninger klienten stadig kan lave, og X-RateLimit-Limit-headeren, det samlede tilladte antal pr. minut.

Opret ordrer i Fabrixa fra din egen butiksfacade eller platform, vedhæft de påkrævede printfiler, og følg hver vare, mens den bevæger sig gennem opfyldelsen.

For at oprette en ordre via Fabrixa Integration API skal du sende en POST anmodning til https://api.fabrixa.com/v2/integration/orders. Anmodningsorganet skal omfatte:

Anmod om kropsstruktur

Eksempel på anmodning

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

For at få opfyldelsesstatus for en specifik ordre skal du sende en GET anmodning til https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Svaret giver en liste over opfyldelser forbundet med ordren, herunder hver varestatus, produktdetaljer og produktionstrinsfremskridt.

Eksempel svar

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

Svaret inkluderer en liste over opfyldelser, der hver giver:

Hver opfyldelsespost svarer til et specifikt produkt eller produktvariant i ordren, og hver kopi af produktet i ordren har sin egen opfyldelsespost - hver vare spores individuelt gennem hele produktionen.

Hvis der ikke returneres nogen opfyldelse af en ordre, er ordren endnu ikke gået ind i behandlingsfasen.

Når du inkluderer kildefiler i din ordre, skal du sikre dig, at de opfylder følgende krav:

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

PDF-krav og siderækkefølge

Rækkefølgen af ​​sider i PDF'en er vigtig. Sider matches til produktlag efter position, og den forventede siderækkefølge afhænger af produkttypen. Sørg for, at siderne i din PDF følger den korrekte lagsekvens for det produkt, du indsender.

Vigtigt: hver PDF-side skal matche de påkrævede dimensioner for sit produktlag og være orienteret korrekt. Placer kunstværket, så toppen af ​​designet flugter med toppen af ​​siden. Forkert sidestørrelse eller -retning kan forårsage problemer med skalering, rotation eller justering i produktionen.

Fabrixa Studio er et værktøj, der lader brugere problemfrit tilpasse og personliggøre produkter i realtid med en intuitiv grænseflade, hvor brugerne kan oprette eller uploade deres egne designs.

Fabrixa Studio er ideel til virksomheder, der tilbyder brugerdefinerede produkter - hvilket gør det muligt for kunderne at visualisere deres design, før de afslutter ordrer.

Du kan integrere Fabrixa Studio på dit websted ved hjælp af en iframe. Dette gør det muligt for dine kunder at tilpasse produkter direkte på dit websted under kassen.

Eksempel iframe til indlejring af 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>

Erstat værdierne for product_sku, cart_item_key og application_key med dine dynamiske værdier.

• application_key - unik nøgle til godkendelse til integrations-API'en.
• product_sku - SKU'en for produktvarianten, hentet fra integrations-API'en.
• .cart_item_key - en unik vare-tilknyttet værdi, der identificerer den indbyggede bil Bruges til at gemme brugertilpasningerne; under ordreoprettelse identificerer den de gemte tilpasninger og tildeler dem til ordren. Se eksempel nedenfor.

Anmodning om at oprette en ordre med 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": {
    "...": "..."
  }
}

Når knappen Tilføj til kurv klikkes inde i iframen, udføres følgende kommando:

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

På samme måde, når der klikkes på knappen Tilbage:

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

postMessage-metoden letter kommunikation på tværs mellem iframen og dens overordnede vindue, så den kan underrette forælderen om specifikke brugerhandlinger.

Det første argument for postMessage er de data, du vil sende. Strengen 'customizationFinished' angiver, at brugeren har afsluttet tilpasningen og tilføjer produktet til indkøbskurven. 'closeButtonClicked' angiver, at brugeren har valgt at gå tilbage.

I det overordnede vindue skal du lytte efter disse beskeder ved hjælp af message begivenhedslytteren:

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

Kontroller altid origin for indgående meddelelser for at sikre, at de kommer fra en pålidelig kilde. Afhængigt af den modtagne besked, udfør de nødvendige handlinger - opdater brugergrænsefladen, bearbejd vognen osv. Validering af origin er afgørende for sikkerheden - det forhindrer uautoriserede scripts i at interagere med din applikation.

Når tilpasningen er fuldført, skal du vise det endelige design ved hjælp af forhåndsvisnings-URL'en nedenfor. Denne URL returnerer et billede af det tilpassede produkt, egnet som src værdien i et <img> tag. Ideel til at vise det tilpassede produkt i din indkøbskurv, ordreoversigt eller hvor som helst i din butiksgrænseflade.

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

Erstat {CART_ITEM_KEY} med den aktuelle nøgle til indkøbskurven og {APPLICATION_KEY} med din gyldige programnøgle.

Eksempel på brug i et billedtag:

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

Webhooks bruges af Fabrixa til at underrette dit system om hændelser i realtid - bestil opdateringer eller kreationer. Når en hændelse opstår, sender Fabrixa en webhook til din server, der indeholder de relevante oplysninger. Din server skal eksponere et offentligt POST-slutpunkt for at håndtere indgående webhooks.

Webhook-anmodningen indeholder følgende overskrifter for at hjælpe dig med at identificere og validere den indgående anmodning:

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

Overskriftsoversigt

• content-type - altid indstillet til application/json for webhooks.
• x-webhook-signature - HMAC-SHA256 signaturen til anmodningsbekræftelse.
• x-webhook-topic af begivenhedstypen eller. For eksempel:
  • order.created - udløses, når en ny ordre oprettes.
  • order.updated - udløses, når en eksisterende ordre opdateres.

Fabrixa webhooks giver dit system besked om ændringer i ordrestatus eller aktivitet. Hver webhook udløses af en specifik x-webhook-topic værdi. Aktuelt understøttede emner:

Ordrestatusser

• Completed - ordren er sendt eller afhentet, og modtagelsen er bekræftet. For digitale produkter har kunden betalt, og filerne er tilgængelige til download.
• Canceled - kunden annullerede betalingen; transaktionen blev ikke gennemført.
• On hold - ordren er midlertidigt blokeret.
• Imported - ordren blev importeret til platformen.

Opfyldelsesstatusser

• Uopfyldt - ordren er ikke blevet forberedt eller sendt ud endnu.
• Delvist opfyldt - nogle varer er blevet behandlet eller afsendt, andre stadig afventer.
• Scheduled - ordren er planlagt og planlagt til behandling.
• Afvist - anmodningen om opfyldelse er blevet afvist, ofte på grund af ugyldige ordredetaljer eller utilgængelighed.
• Opfyldt - ordren er blevet fuldstændig behandlet og leveret eller gjort tilgængelig for kunden.

Et eksempel på nyttelasten sendt med webhook. Denne nyttelast repræsenterer en ordreopdatering:

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

For at sikre, at webhook-anmodningen er autentisk og umanipuleret, skal du kontrollere x-webhook-signature-headeren. Dette involverer genberegning af HMAC-SHA256-signaturen ved hjælp af den rå anmodningsnyttelast og din hemmelige nøgle, og derefter sammenligne den med den modtagne signatur.

Eksempel på rå PHP

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

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

Erstat $yourSecret med din delte hemmelige nøgle. Brug altid hash_equals til at sammenligne signaturer for at afbøde timingangreb.

Webhooks er som standard deaktiveret efter 10 mislykkede leveringsforsøg. Hvis dit slutpunkt returnerer en mislykket status såsom 404 eller en 5xx fejl, vil webhook forsøge igen i alt 10 gange. Hvis den fortsætter med at returnere en ikke-2xx eller ikke-3xx svarkode, vil den blive deaktiveret. Vellykkede svar omfatter:

• 2xx - angiver vellykket behandling, f.eks. 200 OK.
• 301 og 302 - omdirigeringssvar, der angiver, at webhook er blevet håndteret eller videresendt.

Vi anbefaler på det kraftigste, at dit slutpunkt returnerer en 200 OK statuskode så hurtigt som muligt for at bekræfte vellykket modtagelse af webhook. Selvom ethvert 2xx- eller 3xx-svar anses for at være vellykket, er 200 det mest almindeligt anvendte og pålidelige.

For at undgå leveringstimeouts eller genforsøg skal du returnere 200 OK med det samme og håndtere webhook-nyttelastbehandling asynkront, for eksempel via et baggrundsjob eller kø. Hvis dit endepunkt tager for lang tid at reagere, kan det blive betragtet som en fejl, selvom svaret i sidste ende lykkes.

Svar med statuskoder i området 4xx eller 5xx, eller timeouts, vil udløse genforsøg i henhold til genforsøgsmekanismen.