Changelog API

Notifiche di aggiornamento prodotto - ottobre 2026

Invia agli acquirenti di un prodotto un'email che li avvisa che è stato aggiornato — la campagna che un merchant avvia con Notifica clienti sulla pagina di un prodotto — dal tuo sistema. Additivo rispetto al contratto v1. Disponibile su tutti i piani a pagamento.

• Nuovo POST /products/{shopify_product_id}/notifications: mette in coda una campagna (202) per ogni acquirente delle mappature scaricabili del prodotto oppure, con variant_ids, delle mappature che servono quelle varianti. message facoltativo in testo semplice fino a 2.000 caratteri con {customer.first_name}, {shop.name}, {product.title} e {product.metafields.<namespace>.<key>}; nessun link. dry_run esegue tutti i controlli e restituisce conteggi, oggetto e nota renderizzata senza inviare (200; usa una nuova Idempotency-Key per ogni dry run). Costa 10 token del limite di frequenza.
• Nuovo GET /notifications/{notificationId}: stato della campagna, conteggi, waiting_for_archive e un vocabolario chiuso di error; completed con partial: true quando alcuni invii sono falliti. Compaiono anche le campagne avviate dall'app.
• Nuovo POST /notifications/{notificationId}/cancel: annulla una campagna in coda (200). Mantiene il limite di 7 giorni del prodotto, esattamente come l'annullamento dall'app.
• Nuovo oggetto facoltativo notify_customers su POST /mappings e PUT /mappings/{id}: mette in coda una notifica per gli acquirenti della mappatura scritta dopo il commit della scrittura. Una nota che viola una regola sul proprio testo (vuota, troppo lunga, una variabile non valida, più di cinque metacampi, un link nel testo) è 422 invalid_message senza che nulla venga scritto; un problema di metacampo e ogni altro rifiuto sono riportati nel nuovo campo data.notification (created: false, error), mai come 4xx. data.notification è presente solo quando il flag è stato inviato; le risposte esistenti non cambiano.
• Una campagna per prodotto ogni 7 giorni, attraverso tutte le sue varianti e ogni origine, e nessuna finché una è ancora in coda o in invio: 429 notification_cooldown con Retry-After (fino a sette giorni) e error.details.next_available_at. Non è il token bucket — non riprovare automaticamente; pianifica la chiamata successiva a next_available_at.
• Al massimo 5 campagne per negozio in coda o in invio contemporaneamente, attraverso ogni prodotto e ogni origine: una sesta è 429 too_many_active_notifications con error.details.limit e error.details.active_notification_ids, e senza Retry-After. Riprova quando una di esse è terminata. Un dry run viene rifiutato allo stesso modo; in una scrittura di mappatura viene riportato in data.notification.
• Un'email di aggiornamento prodotto per acquirente per negozio ogni 24 ore, attraverso tutte le campagne: un acquirente che ne ha già ricevuta una viene saltato quando la campagna invia. Gli acquirenti saltati non compaiono in sent_count, failed_count o suppressed_count. Una campagna che ha saltato ogni acquirente termina failed con error: recipients_recently_notified e non usa i 7 giorni del prodotto.
• Prima di ogni lotto di massimo 500 email la campagna ricontrolla il negozio e si interrompe se l'abbonamento o il piano a pagamento è scaduto, se le email ai clienti sono state disattivate, se l'invio è stato sospeso o se Alva ha disattivato le notifiche. Se si interrompe prima di aver inviato email a qualcuno è failed (plan_required, email_disabled, notifications_suspended o notifications_switched_off) e rilascia i 7 giorni; se si interrompe più tardi è completed con partial: true. Una campagna in cui ogni invio è fallito è failed con nothing_sent e rilascia anch'essa i 7 giorni, e una che al momento dell'invio non aveva più nessuno a cui scrivere è failed con no_eligible_recipients e li rilascia allo stesso modo.
• Una campagna la cui mappatura interessata ha una rigenerazione dello ZIP in corso la attende (waiting_for_archive: true; solo una mappatura che consegna un archivio ZIP fa attendere una campagna); una rigenerazione fallita, o che non avanza per 60 minuti durante la generazione (6 ore mentre è ancora in attesa di avviarsi o di un nuovo tentativo), contati dalla rigenerazione, non dalla creazione della campagna, fa fallire la campagna con zero invii e rilascia il limite.
• Otto nuovi codici di errore: 403 notifications_suspended, 404 notification_not_found, 409 notification_not_cancellable, 422 invalid_message, 422 no_downloadable_content, 422 no_eligible_recipients, 429 notification_cooldown, 429 too_many_active_notifications. mapping_not_found e multiple_mappings_match acquisiscono error.details.unresolved_variant_ids / ambiguous_variant_ids su questo endpoint.

Aggiornamento dell'accesso - settembre 2026

L'accesso all'API non richiede più l'approvazione.

• Tutti i piani a pagamento (Basic, Pro ed Enterprise) possono usare l'API. Crea le chiavi nell'app in Impostazioni → API keys; non c'è nulla da richiedere.
• Con il piano Free la scheda API keys è nascosta e le chiavi esistenti restituiscono 402 plan_required finché il negozio non passa a un piano a pagamento.

Aggiornamento v1 - luglio 2026

Aggiunte additive di codici di errore e campi di risposta al contratto v1 esistente.

• Nuovo errore 422 withdrawal_consent_required sull'endpoint download-urls degli ordini: viene restituito 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.
• Nuovo errore 422 key_limit_reached alla creazione di chiavi API: un negozio può detenere al massimo 25 chiavi API attive; revocane una prima.
• Nuovo errore 409 delivery_not_yet_released sugli endpoint download-urls e resend degli ordini: viene restituito quando il prodotto ha un ritardo di consegna del download configurato e i file dell'acquirente non sono ancora sbloccati. Finché il ritardo non è trascorso non viene emesso alcun URL di download né inviata alcuna email.
• Nuovo oggetto error.details nella busta di errore: presente solo sui codici che trasportano contesto sicuro per il chiamante. Oggi delivery_not_yet_released è l'unico a produrlo e contiene release_at, l'istante ISO 8601 in cui i download si sbloccano. Considera l'oggetto come aperto: possono comparire nuove chiavi senza un cambio di versione maggiore.
• Nuovi campi delivery_pending e release_at sull'oggetto acquisto dello stato ordine: delivery_pending è true finché un acquisto è ancora trattenuto da un ritardo di consegna del download, mentre release_at è l'istante ISO 8601 dello sblocco, oppure null quando non c'è nulla in sospeso.
• L'endpoint grant-downloads ora rilascia immediatamente gli acquisti trattenuti dell'ordine, così un commerciante può scavalcare un ritardo di consegna del download tramite l'API.

v1.0.0 - giugno 2026

Prima superficie API pilota dietro accesso solo su approvazione.

• API key per gli store approvati.
• Idempotency key obbligatorie sulle richieste di scrittura.
• Import di asset da URL remoto, upload diretti, elenco asset, aggiornamento asset ed eliminazione asset.
• Categorie piatte, mappature di prodotti, pack e tag per license key.
• Assegnazioni di ordini che rendono visibili i download mappati negli account cliente di Shopify.
• Controlli di accesso agli ordini: revoca, ripristino, concessione di download e reinvio dell'email.
• Endpoint per lo stato di job e ordini.
• Download della specifica OpenAPI e della collection Postman.

Politica di versioning

Il contratto v1 è solo additivo: possono essere aggiunti nuovi endpoint, campi facoltativi e nuovi codici di errore. Le modifiche incompatibili useranno un futuro percorso /api/v2.