AmazonAmazon StorefrontAmazon InfluencerAffiliate marketingGuida alle API

API Amazon Storefront: leggi le vetrine dei creator, le liste di idee e i trending pick

Leggi la vetrina di un creator Amazon con una sola chiamata API: profilo, social collegati, liste di idee con il numero di articoli, post curati e trending pick con i prezzi, per 0.5 crediti.

SocQAggiornato il 19 novembre 20266 min di lettura

I creator dell'Amazon Influencer Program gestiscono una vetrina su amazon.com/shop/<name>. Raggruppano i prodotti in liste di idee e post curati, collegano i propri account social e mettono in evidenza i trending pick. Per un team di affiliate o influencer marketing, quella pagina risponde a domande concrete: chi è il creator, dove altro pubblica, cosa consiglia in questa stagione e quanto è grande ogni lista.

Il 2026-11-17 SocQ ha aggiunto l'API Amazon Storefront, che restituisce una vetrina come un unico record strutturato. Questa guida spiega la richiesta, i campi, il prezzo e come inserirla in un flusso di ricerca sui creator.

Risposta rapida: invia l'URL di una vetrina in url a POST /v1/amazon/shop. Interroga GET /v1/tasks/{task_id} finché il task non riesce, poi leggi una riga da data.results.items con il profilo del creator, social_urls, lists, curations e trending_picks. Ogni richiesta costa 0.5 crediti ($0.0025).

Cosa restituisce l'endpoint

1 credito SocQ = $0.005.

EndpointCosa restituiscePrezzo
Amazon Storefront APIUna riga per vetrina: nome del creator, descrizione, avatar, flag top creator, profili social collegati, liste di idee con il numero di articoli, post curati con il numero di prodotti e trending pick con i prezzi0.5 crediti ($0.0025) per chiamata

La riga copre la prima pagina di liste, post curati e trending pick della vetrina. Una vetrina che non esiste fallisce con rimborso, quindi non paghi per gli URL non validi.

Autenticazione e flusso asincrono dei task

Tutte le richieste SocQ si autenticano con una chiave API, e lo stesso header vale per l'invio, lo stato del task e la lettura dei risultati:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Ogni raccolta viene eseguita come task in background:

submit -> task_id -> queued -> running -> succeeded
                                   \-> failed

La risposta all'invio contiene data.task_id e data.status. Interroga il task con quell'ID:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Quando status è succeeded, la risposta include la prima pagina di record normalizzati in data.results.items. limit vale 50 per impostazione predefinita e arriva fino a 500; se has_more è true, passa results.next_cursor come cursor. Mentre un task è queued, running o failed, l'endpoint restituisce i metadati del task senza results.

Un callback_url facoltativo nel corpo dell'invio fa sì che SocQ invii una POST con il riepilogo del task quando termina; leggi poi i record con GET /v1/tasks/{task_id}. Un timeout lato client non annulla il task, quindi riprendi con lo stesso ID invece di pagare un duplicato. 402 indica crediti insufficienti; 429 indica che la chiave ha raggiunto un limite di frequenza o di crediti.

Richiedere una vetrina

L'unico input è url, una vetrina nella forma amazon.com/shop/<name>. Gli altri marketplace Amazon funzionano allo stesso modo.

curl -X POST "https://api.socq.ai/v1/amazon/shop" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/shop/sydneydelrey"
  }'

L'endpoint accetta un URL per richiesta. Per leggere un elenco di vetrine, invia un task per URL, salva ogni task_id insieme al suo input e interrogali in modo indipendente.

Capire il record della vetrina

Un risultato ridotto, tratto dall'esempio della documentazione, ha questo aspetto:

{
  "id": "sydneydelrey",
  "platform": "amazon",
  "resource": "shop",
  "type": "storefront",
  "url": "https://www.amazon.com/shop/sydneydelrey",
  "name": "sydney del rey",
  "is_top_creator": true,
  "social_urls": [
    "https://vm.tiktok.com/ZTFrowSpg/",
    "https://www.youtube.com/channel/UCWvW1JOQ-nsAinO1jLFgrVA",
    "https://www.pinterest.com/sydneydelrey"
  ],
  "lists": [
    {
      "title": "Holiday home goods",
      "url": "https://www.amazon.com/shop/sydneydelrey/list/XYAIGEFWJGML?tag=sydneybertonc-20",
      "items_count": 107
    }
  ],
  "curations": [
    {
      "title": "f/w fit try ons",
      "url": "https://www.amazon.com/shop/sydneydelrey/curation/71fad634-5787-4ee1-bc3c-6e3ca23e5eae",
      "posts_count": 109
    }
  ],
  "trending_picks": [
    {
      "url": "https://www.amazon.com/shop/sydneydelrey/getProductDetails/B0FCLQD6BN?showRelatedPost=true&tag_override=sydneybertonc-20",
      "price": 24.99,
      "discount": null
    }
  ]
}

I campi, raggruppati in base all'uso:

  • Identità del creator: id (il nome della vetrina preso dall'URL), name, text (la descrizione scritta dal creator), avatar_url e is_top_creator, che indica se Amazon segnala il creator come top creator.
  • Presenza su altre piattaforme: social_urls, i profili social collegati nella vetrina.
  • Struttura del catalogo: lists con title, url, image_url e items_count; curations con title, url, image_url e posts_count (il numero di prodotti nel post curato).
  • Promozioni in corso: trending_picks con url, image_url, price nella valuta del marketplace e discount quando è indicato uno sconto.

Ogni riga contiene anche collected_at, il momento in cui SocQ l'ha raccolta. I prezzi cambiano, quindi salva quel timestamp insieme a ogni prezzo che conservi. La tabella completa dei campi è nella documentazione di Amazon Storefront.

Quando usarla

Selezionare partner di affiliazione. is_top_creator, il numero di liste e l'items_count di ciascuna danno un'idea rapida di quanto sia attiva una vetrina prima che qualcuno del team la apra.

Seguire cosa consiglia un creator. Rileggi una vetrina a intervalli regolari e confronta titoli delle liste, conteggi e trending pick tra un'esecuzione e l'altra per capire cosa sta spingendo il creator in questa stagione.

Collegare una vetrina agli account social del creator. social_urls ti dà i profili TikTok, YouTube o Pinterest che il creator collega. Passali alle API Creator per trovare email di lavoro pubbliche, oppure agli endpoint dei profili delle singole piattaforme per il numero di follower.

Ricerca di prodotto. I trending pick rimandano a prodotti. Per avere dati completi sui prodotti, recensioni o classifiche per categoria, usa gli altri endpoint Amazon di SocQ, come l'API Amazon Product Details e l'API Amazon Best Sellers. Per un confronto con le API ufficiali di Amazon, leggi alternative all'Amazon Product Advertising API.

Consigli per la produzione

  1. Normalizza gli URL. Mantieni una sola forma canonica amazon.com/shop/<name> per ogni creator, così non paghi due volte la stessa vetrina.
  2. Aspettati un'istantanea della prima pagina. Liste, post curati e trending pick sono quelli mostrati nella prima pagina della vetrina. Considera i conteggi come un'istantanea al momento di collected_at.
  3. Gestisci i fallimenti a parte. Una vetrina che non esiste fallisce con rimborso. Segnala come rimossa invece di riprovare.
  4. Pianifica il budget in modo semplice. A 0.5 crediti per vetrina, 1,000 vetrine costano 500 crediti, cioè $2.50.

FAQ

Cos'è l'API Amazon Storefront?

È un endpoint SocQ che legge la vetrina di un creator Amazon (amazon.com/shop/<name>) e restituisce profilo del creator, social collegati, liste di idee, post curati e trending pick in un unico record strutturato.

Funziona anche fuori da amazon.com?

Sì. La documentazione indica che gli altri marketplace Amazon funzionano allo stesso modo: invia in url l'URL della vetrina su quel marketplace. I prezzi in trending_picks sono nella valuta di quel marketplace.

Restituisce tutti i prodotti di ogni lista?

No. La riga copre la prima pagina della vetrina: titolo, URL, immagine di copertina e items_count di ogni lista, il numero di prodotti di ogni post curato e i trending pick attuali. Non espande ogni singolo articolo delle liste.

Pago se la vetrina non esiste?

No. Una vetrina che non esiste fallisce con rimborso. Una richiesta riuscita costa 0.5 crediti ($0.0025).

Posso inviare più vetrine in una sola richiesta?

La richiesta accetta un solo url. Invia un task per vetrina e tieni traccia di ogni task_id.

AMAZON API

Prova il flusso di lavoro con un URL pubblico di Amazon

Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.

Scopri le API di Amazon