Riferimento degli endpoint API

Asset

Categorie, mappature, pack, link e tag

POST /mappings e PUT /mappings/{id} accettano un oggetto facoltativo notify_customers ({}, oppure { "message": "…", "variant_ids": [ … ] }). Dopo il commit della scrittura, Alva mette in coda una notifica di aggiornamento prodotto per gli acquirenti della mappatura che hai scritto — la stessa campagna di POST /products/{shopify_product_id}/notifications qui sotto, con le stesse regole per la nota e lo stesso limite di 7 giorni per prodotto. Prima della scrittura vengono eseguiti solo i controlli sul testo stesso della nota: una nota vuota, troppo lunga, che usa una variabile sconosciuta o malformata, che indica più di cinque metacampi o che contiene un link nel testo è 422 invalid_message e non viene scritto nulla. Ogni altro rifiuto è riportato dentro la risposta come data.notification con created: false e un codice error — mai come 4xx, così la scrittura della mappatura riesce comunque. Questo include un problema di metacampo (invalid_message con errors[]: un metacampo mancante, di un tipo non supportato, troppo lungo o che contiene un link, oppure una nota troppo lunga una volta compilate le sue variabili), notification_cooldown con next_available_at, too_many_active_notifications con limit e active_notification_ids, no_eligible_recipients, email_disabled e archive_not_queued quando la rigenerazione dei file non è stata messa in coda. Una mappatura appena creata non ha ancora acquirenti e riporta no_eligible_recipients. data.notification è presente solo quando hai inviato il flag. Il flag non aggiunge costi di limite di frequenza: la scrittura della mappatura costa i soliti 2 token. Riproporre la stessa Idempotency-Key restituisce la risposta memorizzata senza una seconda campagna; per ritentare solo la notifica, chiama POST /products/{shopify_product_id}/notifications con una nuova chiave e variant_ids con le varianti della mappatura scritta, o con gli stessi variant_ids del flag. Senza variant_ids quell'endpoint notifica gli acquirenti di tutte le mappature del prodotto, non solo di quella che hai scritto.

Un flag per prodotto, non uno per variante. Il flag invia l'email solo agli acquirenti della mappatura che hai scritto, ma usa il limite di 7 giorni dell'intero prodotto. Se scrivi le mappature delle varianti di un prodotto una alla volta con il flag su ciascuna, la prima campagna occupa i 7 giorni del prodotto, quindi le altre riportano notification_cooldown. Metti invece il flag su una sola scrittura, l'ultima, così la campagna attende anche le rigenerazioni messe in coda dalle scritture precedenti. Indica in variant_ids ogni variante i cui acquirenti devono esserne informati, comprese quelle della mappatura scritta: variant_ids sostituisce l'ambito predefinito invece di aggiungersi a esso.

Ordini e accesso

L'endpoint download-urls restituisce 422 withdrawal_consent_required quando il negozio ha attivato il consenso al diritto di recesso UE e l'ordine non ha ancora un record di consenso; gli URL di download vengono emessi non appena il cliente acconsente.

Gli endpoint download-urls e resend restituiscono 409 delivery_not_yet_released quando il prodotto ha un ritardo di consegna del download configurato e i file dell'acquirente non sono ancora sbloccati. Il valore error.details.release_at è l'istante ISO 8601 dello sblocco e l'endpoint grant-downloads rilascia l'ordine in anticipo.

Notifiche di aggiornamento prodotto

Invia agli acquirenti di un prodotto un'email che li avvisa che è stato aggiornato — la stessa campagna che un merchant avvia con Notifica clienti sulla pagina di un prodotto nell'app — dal tuo sistema. Disponibile su tutti i piani a pagamento; 403 forbidden significa che l'API è disattivata per l'app (l'interruttore di emergenza globale) o che Alva ha disattivato la funzione — contattaci se ricevi questa risposta. Nel percorso, {shopify_product_id} è l'id numerico nudo del prodotto (consigliato) o un GID codificato in percentuale come un unico segmento di percorso (gid%3A%2F%2Fshopify%2FProduct%2F123); un gid://shopify/Product/123 letterale occupa più segmenti di percorso e non raggiunge la route.

Corpo della richiesta (ogni campo è facoltativo; {} notifica l'intero prodotto senza nota). message: una nota in testo semplice fino a 2.000 caratteri, mostrata come "Un messaggio da {il tuo negozio}:" sopra il pulsante di download. La nota serve a descrivere cosa è cambiato nel prodotto — correzioni, nuovi file, cosa scaricare di nuovo — e non deve essere usata per promozioni o sconti. Può usare {customer.first_name}, {shop.name}, {product.title} e {product.metafields.<namespace>.<key>} (fino a cinque metacampi di tipo testo, numero, data o elenco di testo; gli altri tipi vengono rifiutati). I link non sono consentiti in nessun punto della nota — indirizzi web, www., domini nudi e indirizzi email vengono rifiutati, anche all'interno del valore di un metacampo — e una variabile sconosciuta viene rifiutata invece di essere lasciata come testo. Un message presente ma vuoto viene rifiutato; ometti il campo per non inserire alcuna nota. variant_ids: limita la campagna alle mappature che servono quelle varianti (id nudi o GID, al massimo 100); omettilo per l'intero prodotto. Un array vuoto è 400 invalid_request, mai "tutto". dry_run: vedi la tabella.

A chi viene inviata l'email. Per impostazione predefinita a ogni mappatura del prodotto che ha file, pack o link; le mappature solo chiavi e personalizzate vengono saltate. Un acquirente conta una sola volta indipendentemente da quante varianti interessate ha acquistato, e il pulsante apre il suo acquisto più recente. Gli acquirenti che hanno rifiutato le email di aggiornamento prodotto vengono saltati e contati in opted_out_count.

Una campagna per prodotto ogni 7 giorni, attraverso tutte le sue varianti e ogni origine — questo endpoint, il flag notify_customers in una scrittura di mappatura e il pulsante del merchant. Entro quella settimana, e finché una campagna per il prodotto è ancora in coda o in invio, la risposta è 429 notification_cooldown con Retry-After (secondi, fino a sette giorni) e error.details.next_available_at. Non è il token bucket per chiave: non riprovare automaticamente — un ciclo di retry basato sul 429 girerebbe per una settimana. Pianifica la chiamata successiva a next_available_at. Annullare una campagna non restituisce al prodotto i suoi 7 giorni; usa dry_run per verificare una nota prima di inviare. Una campagna che fallisce con zero invii rilascia invece il limite, quindi può semplicemente essere ritentata.

Al massimo 5 campagne per negozio contemporaneamente. Un negozio può avere al massimo 5 campagne in coda o in invio nello stesso momento, attraverso tutti i suoi prodotti e ogni origine. Una sesta è 429 too_many_active_notifications: error.details.limit è il limite e error.details.active_notification_ids elenca le campagne in coda o in invio di questo negozio, dalla più vecchia. Non c'è alcun Retry-After; interroga GET /notifications/{id} per una di esse e riprova quando sarà terminata. Un dry run viene rifiutato allo stesso modo. In una scrittura di mappatura viene riportato in data.notification, mai come 4xx.

Un'email di aggiornamento prodotto per acquirente al giorno. Un acquirente riceve al massimo un'email di aggiornamento prodotto da un negozio in qualsiasi arco di 24 ore, conteggiata per indirizzo email, attraverso ogni campagna, prodotto e origine. La regola si applica al momento dell'invio della campagna: un acquirente che ne ha già ricevuta una viene saltato, e questo non conta come invio fallito. Gli acquirenti saltati non vengono contati in sent_count, failed_count o suppressed_count, quindi recipient_count può essere maggiore della loro somma. Una campagna in cui ogni acquirente è stato saltato termina failed con error: recipients_recently_notified e non usa i 7 giorni del prodotto. Una in cui solo alcuni sono stati saltati si completa normalmente e li usa.

L'attesa dell'archivio. Se l'archivio ZIP di una mappatura interessata è in rigenerazione — hai appena sostituito i suoi file — la campagna attende che la rigenerazione sia terminata, così nessun acquirente scarica il vecchio archivio: waiting_for_archive: true sul 202 e sulla GET. Solo una mappatura che consegna un archivio ZIP fa attendere una campagna. Una rigenerazione che fallisce, o che non avanza per 60 minuti durante la generazione (6 ore mentre è ancora in attesa di avviarsi o di un nuovo tentativo), contati dall'ultimo cambio di stato della rigenerazione, non da quando è stata creata la campagna, fa fallire la campagna con zero invii (error è archive_build_failed o archive_not_ready) e rilascia il limite; correggi i file e riprova.

Idempotenza. Un 202 viene riproposto per 24 ore sotto la stessa chiave (stesso id, nessuna seconda campagna). I rifiuti non vengono mai memorizzati, quindi un nuovo tentativo con la stessa chiave dopo next_available_at viene valutato di nuovo. Usa una nuova Idempotency-Key per ogni dry run: una chiave riproposta restituisce l'anteprima memorizzata, e la stessa chiave con e senza dry_run è 409 idempotency_conflict.

Stato sulla GET. queued → processing → completed, failed o cancelled. completed con partial: true significa che alcuni invii sono falliti o sono stati soppressi (vedi sent_count, failed_count, suppressed_count), oppure che l'invio si è interrotto a metà (vedi sotto). Su failed, error è uno tra interrupted, worker_crashed, send_aborted, archive_build_failed, archive_not_ready, email_disabled, invalid_message, plan_required, notifications_suspended, notifications_switched_off, nothing_sent, recipients_recently_notified, no_eligible_recipients, failed. source è admin, api o api_mapping.

Controlli durante l'invio. Prima di ogni lotto di massimo 500 email la campagna ricontrolla il negozio. Si interrompe se l'abbonamento è diventato inattivo o il negozio è passato al piano Free (plan_required), se le email ai clienti sono state disattivate (email_disabled), se l'invio è stato sospeso a seguito di reclami (notifications_suspended) o se Alva ha disattivato le notifiche (notifications_switched_off). Se si interrompe prima di aver inviato email a qualcuno, la campagna è failed con quel codice error e i 7 giorni del prodotto vengono rilasciati. Se si interrompe dopo aver inviato email ad alcuni acquirenti, è completed con partial: true. nothing_sent significa che ogni invio è fallito, quindi nessuno ha ricevuto email; anche in questo caso i 7 giorni vengono rilasciati. no_eligible_recipients significa che al momento dell'invio della campagna non restava nessuno a cui scrivere (ogni acquirente si era disiscritto o aveva perso l'accesso ai download), quindi non è stato inviato nulla e i 7 giorni vengono rilasciati.

Rifiuti. 402 plan_required (il negozio è sul piano Free o il suo abbonamento non è attivo), 403 forbidden (l'API è disattivata per l'app o Alva ha disattivato la funzione — contattaci), 403 notifications_suspended (invio sospeso a seguito di reclami — contatta l'assistenza), 404 mapping_not_found (nessuna mappatura per il prodotto, o una variante che nessuna mappatura serve o che Shopify non elenca tra le varianti del prodotto — error.details.unresolved_variant_ids), 409 multiple_mappings_match (error.details.ambiguous_variant_ids), 409 personalized_product, 422 invalid_message (error.details.errors[] indica ogni regola violata, error.details.max_length è il limite), 422 email_disabled (le email ai clienti sono disattivate nell'app), 422 no_downloadable_content, 422 no_eligible_recipients (error.details.opted_out_count), 429 notification_cooldown, 429 too_many_active_notifications (error.details.limit, error.details.active_notification_ids), 409 app_not_installed (la nota fa riferimento a un metacampo o hai inviato variant_ids, e Alva non ha una sessione Shopify attiva per il negozio, di solito perché l'app è stata disinstallata), 500 internal_error (per esempio Shopify non è riuscito a restituire i metacampi del prodotto per la nota o a confermare le varianti richieste, oppure la creazione ha atteso più di 8 secondi dietro le altre creazioni del negozio: ogni 500 di questo endpoint rilascia l'Idempotency-Key, quindi riprova la stessa richiesta con la stessa chiave; se il tentativo fallito ha comunque messo in coda la campagna, il nuovo tentativo viene rifiutato con 429 notification_cooldown invece di avviarne una seconda). GET e cancel rispondono 404 notification_not_found per un id mancante o di un altro negozio, e cancel risponde 409 notification_not_cancellable con error.details.status una volta che una campagna ha lasciato la coda. Consulta la pagina degli errori per sapere cosa fare in ciascun caso.

Salute e stato