Zum Hauptinhalt springen

Integrationsleitfaden

Fabrixa API Integrationsleitfaden - Autorisierung, erste Bestellung, Webhook-Behandlung, Fehlerbehebung
ENTWICKLER - INTEGRATIONSLEITFADEN

Genehmigung zur Erfüllung in fünfzehn Minuten.

Copy-Paste-Walkthrough des Fabrixa REST API: Authentifizierung, Liste der verfügbaren Produkte, eine Bestellung aufgeben, einen Webhook registrieren, die Lebenszyklusereignisse behandeln. JSON über HTTPS, Inhaber-Token-Authentifizierung, idempotente Anfragen, wiederholungssichere Webhooks. Keine Überraschungen.

REST + JSON - INHABER-AUTHENTIFIZIERUNG - IDEMPOTENT - WEBHOOK-GESTEUERT

VORAUSSETZUNGEN

Was Sie brauchen, bevor Sie anfangen.

01
API-SCHLÜSSEL

Wird über das Dashboard Ihres Fabrixa-Kontos ausgestellt. Sandbox-Schlüssel für die Entwicklung, Produktionsschlüssel für Live-Bestellungen. Beide sind Inhaber-Token.

02
WEBHOOK-ENDPUNKT

Ein öffentlich erreichbarer HTTPS-Endpunkt auf Ihrer Seite, der JSON POST-Anfragen annehmen kann. Localhost funktioniert in Dev über Tunnelling-Tools.

03
KUNSTWERK DATEIEN

Druckfähiges Bildmaterial, das über eine HTTPS-URL zugänglich ist. Adobe Illustrator, Photoshop, Raster- oder Vektordaten. Wir rufen die Datei ab, wenn wir den Druckauftrag rendern.

SCHRITT 1 - AUTHENTIFIZIERUNG

Testen Sie die Taste API mit einem Begrüßungsanruf.

Bearer-Token-Authentifizierung. Die Basis-URL der Sandbox lautet https://sandbox.api.fabrixa.com/v1; Produktion tauscht die Subdomain aus.

GET /v1/account
# Überprüfung von Autorisierung und Kontozugriff
locken. https://sandbox.api.fabrixa.com/v1/account \
  -H "Autorisierung: Bearer $FABRIXA_API_KEY" \
  -H "Akzeptieren: application/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "Umwelt": "Sandkasten",
  "Stufe": "Produktion",
  "Webhook-URL": null
}

Ein 401 bedeutet, dass der Schlüssel falsch ist oder widerrufen wurde. Erzeugen Sie einen neuen Schlüssel über das Dashboard. Ein 403 bedeutet, dass der Schlüssel gültig ist, Sie aber keine Berechtigung für die Ressource haben (selten bei /Konto).

SCHRITT 2 - LISTE DER PRODUKTE

Entdecken Sie die SKUs, die für Ihr Konto verfügbar sind.

Gibt den Katalog mit Produkt-IDs, Grundmaterialien, Größen und Preisstufen zurück. Lokaler Cache; die Aktualisierung des Katalogs erfolgt nicht pro Anfrage.

GET /v1/Produkte
GET /v1/products?category=kleider&page=1&limit=20

# Antwort (gekürzt)
{
  "Daten": [
    {
      "produkt_id": "prod_tee_unisex_aop",
      "Kategorie": "apparel.tees-tops",
      "Name": "Unisex-T-Shirt AOP",
      "Basis": "organic-cotton-160gsm",
      "Größen": ["XS","S","M","L","XL","XXL"],
      "drucken": "reaktiv-aop",
      "produktions_hub": "PT",
      "Vorlaufzeit_Tage": { "min": 6, "max": 9 }
    }
  ],
  "Seite": 1,
  "has_more": wahr
}
SCHRITT 3 - EINE BESTELLUNG AUFGEBEN

Idempotente Auftragserstellung.

Einstellung Idempotenz-Schlüssel bei jeder Auftragsanfrage - sicher, um denselben Aufruf zu wiederholen, ohne doppelte Aufträge zu erzeugen. Verwenden Sie eine UUID pro logischem Auftrag auf Ihrer Seite.

POST /v1/orders
POST /v1/aufträge
Idempotenz-Schlüssel: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "auftrag_ref": "shopify-1042",
  "Gegenstände": [
    {
      "produkt_id": "prod_tee_unisex_aop",
      "Größe": "L",
      "Menge": 2,
      "artwork_url": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "Empfänger": {
    "Name": "Lena Costa",
    "adresse_zeile1": "Rua das Flores 12",
    "Stadt": "Porto",
    "Land": "PT",
    "Postleitzahl": "4050-262"
  },
  "Verpackung": "White-Label"
}

# 201 Erstellt
{
  "order_id": "ord_8e6f4b2a",
  "Status": "erhalten",
  "geschätzter_Versand": "2026-05-15",
  "webhook_events": ["auftrag.gedruckt","auftrag.abgefertigt"]
}
SCHRITT 4 - WEBHOOK-ENDPUNKT

Abonnieren Sie den Lebenszyklus der Bestellung.

Legen Sie die Webhook-URL einmal auf Kontoebene fest. Die Lebenszyklus-Ereignisse jeder Bestellung POST an diese URL. Überprüfen Sie die HMAC-Signatur vor der Verarbeitung.

PUT /v1/account/webhook
PUT /v1/account/webhook

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "Ereignisse": [
    "Bestellung.erhalten",
    "auftrag.gedruckt",
    "auftrag.abgefertigt",
    "auftrag.fehlgeschlagen"
  ]
}

# Webhook-Nutzdaten (POST an Ihren Endpunkt)
{
  "Ereignis": "auftrag.abgefertigt",
  "order_id": "ord_8e6f4b2a",
  "auftrag_ref": "shopify-1042",
  "Zeitstempel": "2026-05-15T11:32:08Z",
  "Verfolgung": {
    "Träger": "DHL",
    "tracking_number": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Vollständiger Veranstaltungshinweis und Unterschriftenprüfung auf dem Webhaken-Seite.

FEHLERBEHANDLUNG UND RATENBEGRENZUNG

Was zu erwarten ist, wenn etwas schief geht.

FORM DER FEHLERREAKTION

Fehler sind JSON, niemals HTML.

Fehlerreaktion
{
  "Fehler": {
    "code": "artwork_unreachable",
    "Nachricht": "GET auf artwork_url fehlgeschlagen (Timeout 30s)",
    "anfrage_id": "req_94kQ7r2L",
    "wiederholbar": wahr
  }
}

Codes sind stabile Strings - sicher zum Einschalten. wiederholbar: wahr bedeutet, dass es sicher ist, es mit demselben Idempotenzschlüssel erneut zu versuchen.

RATE LIMITS

Schiebefenster, Kopfzeilen geben das Budget an.

  • Sandkasten: 60 Anforderungen / Minute pro Taste
  • Produktion: 600 Abrufe / Minute pro Schlüssel (Erhöhung auf Anfrage)
  • Überschriften: X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 Antwort auf Überschreitung mit Wiederholungsversuch nach Sekunden
  • Webhook-Lieferungen werden nicht auf Ihr Inbound-Budget angerechnet.
HÄNGENGEBLIEBEN?

Sprechen Sie mit einem Lösungsingenieur.

Für Integrationsunterstützung, Sandbox-Key-Probleme, kundenspezifische Anforderungen oder Kapazitätsplanung - Technischer SE-Kanal anstelle der Vertriebslinie. Durchschnittliche Antwort innerhalb eines Werktages.

Wagen (0 Artikel)

Erstellen Sie Ihr Konto