REST API

API di prova virtuale

Integra la prova virtuale di Irisphera in un negozio o in un'app personalizzati con la REST API: autenticazione, sessioni acquirente e generazione della prova virtuale.

Richiedi una chiave API

In questa pagina

Prima di iniziare
Panoramica
Autenticazione
Endpoint in sintesi
1. Aggiungi i tuoi prodotti
2. Crea una sessione acquirente
3. Genera una prova virtuale
Errori
Utilizzo

Prima di iniziare#

Una chiave API da commerciante, rilasciata da Irisphera
Un server sotto il tuo controllo, per mantenere segreta la chiave e creare le sessioni acquirente
Prodotti in una collezione Irisphera, identificati dal tuo SKU

Panoramica#

L'API è servita da https://api.irisphera.com e restituisce gli errori come application/problem+json. Ogni generazione di prova virtuale costa 0,06 €. Vedi il calcolatore nella pagina dei prezzi.

Il riferimento completo dell'API viene condiviso insieme alla tua chiave API. Questa pagina descrive il flusso principale.

Autenticazione#

Chiamante	Header	Da usare per
Il tuo server	`MERCHANT-API-KEY: <key>`	Catalogo, sessioni acquirente e utilizzo. Non inserirla mai nel codice del browser o delle app mobili.
Browser o app dell'acquirente	`Authorization: Bearer <token>`	Chiamate di prova virtuale, con un token a breve scadenza creato dal tuo server.

Endpoint in sintesi#

Metodo	Percorso	Scopo
POST	`/merchant/v2/collection-context`	Ottieni il tuo canale per le sessioni acquirente
POST	`/merchant/v2/shopper-sessions`	Apri una sessione acquirente
POST	`/merchant/v2/shopper-sessions/{sessionId}/access-tokens`	Rinnova un token acquirente
GET	`/shopper/v2/stylist-preview/{skuCustomId}`	Verifica se un prodotto supporta la prova virtuale
POST	`/shopper/v2/stylist-preview`	Genera una prova virtuale
GET	`/merchant/v1/subscription`	Controlla quota e utilizzo

1. Aggiungi i tuoi prodotti#

Crea una collezione e aggiungici i prodotti, identificati dal tuo SKU (skuCustomId). Puoi anche importare una collezione da un URL di feed.

2. Crea una sessione acquirente#

Sul tuo server, recupera una volta il tuo canale con POST /merchant/v2/collection-context, poi apri una sessione per ogni acquirente. La risposta include un accessToken e la sua scadenza expiresAt. Rinnovalo con POST /merchant/v2/shopper-sessions/{sessionId}/access-tokens.

Crea una sessione

curl https://api.irisphera.com/merchant/v2/shopper-sessions \
  -H "MERCHANT-API-KEY: $IRISPHERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "<channelId>",
    "currentIdentity": {
      "namespace": "<namespace>",
      "kind": "ANONYMOUS",
      "externalId": "visitor-123"
    }
  }'

3. Genera una prova virtuale#

Verifica che un prodotto sia pronto con GET /shopper/v2/stylist-preview/{skuCustomId}. Se la categoria è UNAVAILABLE, non offrire la prova virtuale per quel prodotto.

Poi invia la foto dell'acquirente insieme allo SKU del prodotto. La risposta contiene generatedImage come WebP in base64, oltre a un resultUrl valido per 24 ore.

Genera una prova virtuale

curl https://api.irisphera.com/shopper/v2/stylist-preview \
  -H "Authorization: Bearer $SHOPPER_TOKEN" \
  -F skuCustomId=DRESS-LILAC-S \
  -F [email protected] \
  -F isFaceBlurred=false

Nota

Formati di foto accettati: PNG, JPEG, WebP e AVIF.

Errori#

Gli errori usano il formato application/problem+json, con uno stato, un titolo e dettagli che puoi registrare nei log.

Importante

Una risposta 420 significa che la foto dell'acquirente non è utilizzabile. Chiedine un'altra invece di riprovare con la stessa immagine.

Utilizzo#

Controlla la tua quota e l'utilizzo attuale con GET /merchant/v1/subscription.

Questa pagina ti è stata utile?