Vai al contenuto principale

Guida all'integrazione

Guida all'integrazione Fabrixa API - autenticazione, primo ordine, gestione dei webhook, recupero degli errori
SVILUPPATORI - GUIDA ALL'INTEGRAZIONE

Dall'autorizzazione all'adempimento in quindici minuti.

Copia-incolla del REST Fabrixa API: autenticazione, elenco dei prodotti disponibili, effettuare un ordine, registrare un webhook, gestire gli eventi del ciclo di vita. JSON su HTTPS, Autenticazione tramite bearer-token, richieste idempotenti, webhook sicuri per i tentativi. Nessuna sorpresa.

REST + JSON - BEARER AUTH - IDEMPOTENTE - WEBHOOK-DRIVEN

PREREQUISITI

Cosa vi serve prima di iniziare.

01
CHIAVE API

Rilasciata dal cruscotto dell'account Fabrixa. Chiave Sandbox per lo sviluppo, chiave di produzione per gli ordini in tempo reale. Entrambi sono gettoni al portatore.

02
ENDPOINT WEBHOOK

Un endpoint HTTPS raggiungibile pubblicamente sul proprio lato, in grado di accettare richieste JSON POST. Localhost funziona in dev tramite strumenti di tunnelling.

03
FILES D'ARTE

Opere d'arte pronte per la stampa accessibili tramite URL HTTPS. Adobe Illustrator, Photoshop, raster o vettoriale. Il file viene recuperato durante il rendering del lavoro di stampa.

FASE 1 - AUTENTICAZIONE

Testate la chiave API con una chiamata di benvenuto.

Autenticazione con bearer-token. L'URL di base della Sandbox è https://sandbox.api.fabrixa.com/v1; la produzione scambia il sottodominio.

GET /v1/account
# Verifica dell'autorizzazione e dell'accesso all'account
ricciolo https://sandbox.api.fabrixa.com/v1/account \
  -H "Autorizzazione: Bearer $FABRIXA_API_KEY" \
  -H "Accetta: application/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "ambiente": "sandbox",
  "livello": "produzione",
  "indirizzo_url_webhook": nullo
}

Un 401 significa che la chiave è sbagliata o revocata. Generarne una nuova dalla dashboard. Un 403 significa che la chiave è valida, ma non si ha l'autorizzazione per la risorsa (raro su /conto).

FASE 2 - ELENCO DEI PRODOTTI

Scoprite gli SKU disponibili per il vostro conto.

Restituisce il catalogo con gli ID dei prodotti, i materiali di base, le dimensioni e i livelli di prezzo. La cache è locale; l'aggiornamento del catalogo non è per richiesta.

GET /v1/prodotti
GET /v1/prodotti?categoria=abbigliamento&pagina=1&limite=20

# Risposta (troncata)
{
  "dati": [
    {
      "product_id": "prod_tee_unisex_aop",
      "categoria": "apparel.tees-tops",
      "nome": "Maglietta unisex AOP",
      "base": "organic-cotton-160gsm",
      "dimensioni": ["XS","S","M","L","XL","XXL"],
      "stampa": "reattivo-aop",
      "production_hub": "PT",
      "lead_time_days": { "min": 6, "max": 9 }
    }
  ],
  "pagina": 1,
  "has_more": vero
}
FASE 3 - EFFETTUARE UN ORDINE

Creazione di ordini idempotenti.

Set Chiave dell'idempotenza su ogni richiesta d'ordine - in modo da poter riprovare la stessa chiamata senza creare ordini duplicati. Utilizzate un UUID per ogni ordine logico da parte vostra.

POST /v1/ordini
POST /v1/ordini
Chiave dell'idempotenza: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "ordine_ref": "shopify-1042",
  "elementi": [
    {
      "product_id": "prod_tee_unisex_aop",
      "dimensione": "L",
      "quantità": 2,
      "url_opera_d_arte": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "destinatario": {
    "nome": "Lena Costa",
    "indirizzo_linea1": "Rua das Flores 12",
    "città": "Porto",
    "paese": "PT",
    "codice_postale": "4050-262"
  },
  "imballaggio": "etichetta bianca"
}

# 201 Creato
{
  "order_id": "ord_8e6f4b2a",
  "stato": "ricevuto",
  "stima_spedizione": "2026-05-15",
  "webhook_events": ["ordine.stampato","ordine.spedito"]
}
PASSO 4 - ENDPOINT WEBHOOK

Iscriversi al ciclo di vita dell'ordine.

Impostare l'URL del webhook una sola volta a livello di account. Ogni evento del ciclo di vita dell'ordine POST a tale URL. Verificare la firma HMAC prima dell'elaborazione.

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

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "eventi": [
    "ordine.ricevuto",
    "ordine.stampato",
    "ordine.spedito",
    "ordine.fallito"
  ]
}

Carico utile del webhook # (POST all'endpoint)
{
  "evento": "ordine.spedito",
  "order_id": "ord_8e6f4b2a",
  "ordine_ref": "shopify-1042",
  "timestamp": "2026-05-15T11:32:08Z",
  "tracciamento": {
    "vettore": "DHL",
    "numero_di_tracciamento": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Riferimento completo all'evento e verifica della firma sul pagina webhooks.

GESTIONE DEGLI ERRORI E LIMITI DI VELOCITÀ

Cosa aspettarsi quando le cose vanno male.

FORMA DELLA RISPOSTA ALL'ERRORE

Gli errori sono JSON, mai HTML.

Risposta all'errore
{
  "errore": {
    "codice": "artwork_unreachable",
    "messaggio": "GET su artwork_url fallito (timeout 30s)".",
    "request_id": "req_94kQ7r2L",
    "ritentabile": vero
  }
}

I codici sono stringhe stabili - sicure da accendere. ritentare: true significa che è sicuro riprovare con la stessa chiave di idempotenza.

LIMITI DI TASSO

Finestra scorrevole, le intestazioni indicano il budget.

  • Sandbox: 60 richieste / minuto per chiave
  • Produzione: 600 req / minuto per chiave (aumento su richiesta)
  • Intestazioni: X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 risposta sul sovraccarico con Riprova dopo secondi
  • Le consegne di webhook non vengono conteggiate nel budget inbound.
BLOCCATO?

Parlate con un ingegnere delle soluzioni.

Per l'assistenza all'integrazione, i problemi di sandbox-key, i requisiti personalizzati o la pianificazione della capacità canale tecnico SE piuttosto che la linea di vendita. Risposta media entro un giorno lavorativo.

Carrello (0 articoli)

Crea il tuo account