Passa al contenuto principale

Changelog

Tutte le modifiche rilevanti all'API Qlara Platform sono documentate in questa pagina. Ogni release è elencata con il numero di versione, la data e un riepilogo di ciò che è stato aggiunto, modificato, migliorato o corretto.

Seguiamo il Versionamento Semantico: MAJOR.MINOR.PATCH.

  • MAJOR -- modifiche non retrocompatibili che richiedono aggiornamenti lato client.
  • MINOR -- nuove funzionalità ed endpoint, retrocompatibili.
  • PATCH -- correzioni di bug e miglioramenti minori.

v1.4.0 -- Settembre 2026​

Aggiunto​

  • Header di risposta X-Request-Id: ogni risposta include ora l'identificativo di traccia che la piattaforma ha assegnato alla richiesta, anche in caso di errore. Citalo quando contatti il supporto per una chiamata specifica.

Modificato​

  • Stati di consegna normalizzati: tutti gli endpoint di tracciamento delle consegne riportano un unico insieme di deliveryStatus, ACCEPTED, REJECTED, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ERROR, DISABLED, UNSUPPORTED, CONVERSATION_CLOSED e UNKNOWN, con descrizioni in minuscolo (delivered, undeliverable, general error, ...). Il webhook di stato consegna invia gli stessi codici numerici come statusCode. SENT e RECEIVED non vengono più restituiti. Vedi Delivery Statuses.
  • Invii rifiutati: POST /api/partner-gateway/v1/sms/messages, /rcs/messages e /whatsapp/messages rispondono 422 con un corpo JSend fail, invece di 202, quando la piattaforma di messaggistica rifiuta il messaggio. Se un canale di fallback ha accettato il messaggio, la risposta resta 202.

Corretto​

  • Parametri data dello storico messaggi: GET /api/partner-gateway/v1/messages/history accetta from e to come data (2026-08-27, l'intera giornata UTC), data-ora senza offset (letta come UTC) o ISO 8601 con offset. Un valore in un'altra forma, o un from successivo a to, riceve 400 con i formati accettati invece di un 404 senza spiegazioni.
  • Parametro channel: channel viene letto senza distinzione tra maiuscole e minuscole sugli endpoint di storico e stato di consegna, e un valore sconosciuto riceve 400 invece di 404.
  • Dettaglio messaggi inbox: GET /api/partner-gateway/v1/inbox/conversations/{chatId}/messages non fallisce più con 500.
  • Stato di consegna degli SMS: gli SMS non vengono più riportati come UNKNOWN. Un SMS ancora in transito risulta ACCEPTED, e il suo stato definitivo segue all'arrivo della ricevuta del carrier.

Documentazione​

  • Limiti di frequenza: gli header X-RateLimit-* e la tabella per piano non sono mai stati implementati e sono stati rimossi. Gli endpoint di messaggistica applicano un limite di richieste al secondo per account, segnalato con 429 e Retry-After; gli endpoint Platform non ne applicano. Vedi Panoramica API.
  • Paginazione: le collezioni sono paginate per pagina (page da 0, limit) e restituiscono data, page, limit, totalCount e totalPages. La forma offset/pagination documentata in precedenza non è mai esistita; gli endpoint che restituiscono un array semplice sono elencati nella Panoramica API.
  • Corpi di errore documentati nella loro reale forma JSend, e flusso di export del caso d'uso sullo storico messaggi allineato agli endpoint reali.
  • Webhook: le guide sui webhook mostrano ora le risposte reali degli endpoint di gestione (201 con companyId e callbackUrl, 409 se un webhook esiste già, 204 all'eliminazione), i payload reali di DELIVERY, READ e INBOUND e la reale politica di retry.

v1.3.0 -- Maggio 2026​

Aggiunto​

  • Assegnazione conversazioni: assegna e rimuovi l'assegnatario di una conversazione della posta in arrivo ed elenca i membri del team della tua azienda che possono essere assegnati.
    • GET /api/partner-gateway/v1/inbox/conversations/{chatId} -- recupera una singola conversazione, incluso il suo assegnatario corrente.
    • POST /api/partner-gateway/v1/inbox/conversations/{chatId}/assignee -- assegna una conversazione a un membro del team della tua azienda.
    • DELETE /api/partner-gateway/v1/inbox/conversations/{chatId}/assignee -- rimuovi l'assegnatario da una conversazione.
    • GET /api/partner-gateway/v1/inbox/conversations/assignable-users -- elenca gli utenti che possono essere assegnati alle conversazioni.
  • Filtro sezione inbox: nuovo query parameter opzionale section su GET /api/partner-gateway/v1/inbox/conversations per restringere i risultati in base allo stato di assegnazione.

v1.2.0 -- Aprile 2026​

Aggiunto​

  • Endpoint Social Profiles: recupera gli account social collegati al tuo account Qlara.
    • GET /api/partner-gateway/v1/socials -- elenca tutti i profili social collegati (Facebook, Instagram, LinkedIn, Google, TikTok).
    • GET /api/partner-gateway/v1/socials/{platform} -- ottieni i dettagli del profilo per una piattaforma specifica.
  • Documentazione multi-lingua: il portale sviluppatori è ora disponibile in inglese e italiano. Cambia lingua dalla barra di navigazione.
  • Collezioni Postman: collezioni .json scaricabili per ogni gruppo API (Qlara Platform, SMS Universal, SMS Legacy, RCS Send, RCS Templates, WhatsApp). Importa in Postman e inizia subito a testare.
  • Pagina SDK e Librerie: esempi di integrazione rapida per Node.js, Python, PHP, Java, Go e C#.

Migliorato​

  • Redesign del portale sviluppatori: sito di documentazione aggiornato con diagrammi di sequenza Mermaid, tab per esempi multi-linguaggio e accordion FAQ per una navigazione più rapida.
  • Pagina Panoramica API: aggiunta documentazione completa per limiti di frequenza, paginazione, gestione errori e strategie di retry.

v1.1.0 -- Marzo 2026​

Aggiunto​

  • Conversazioni inbox: gestione completa delle conversazioni per i messaggi in arrivo.
    • GET /api/partner-gateway/v1/inbox -- elenca tutte le conversazioni con filtri e paginazione.
    • GET /api/partner-gateway/v1/inbox/{conversationId} -- ottieni una singola conversazione con lo storico dei messaggi.
    • POST /api/partner-gateway/v1/inbox/{conversationId}/reply -- rispondi a una conversazione.
    • POST /api/partner-gateway/v1/inbox/{conversationId}/archive -- archivia una conversazione.
    • POST /api/partner-gateway/v1/inbox/{conversationId}/read -- segna una conversazione come letta.
  • Gestione media: carica e gestisci file multimediali da utilizzare nei messaggi RCS e WhatsApp.
    • POST /api/partner-gateway/v1/media -- carica un file multimediale (immagine, video, documento, audio).
    • GET /api/partner-gateway/v1/media -- elenca i media caricati con filtri per tipo e data.
    • DELETE /api/partner-gateway/v1/media/{mediaId} -- elimina un file multimediale caricato.

Migliorato​

  • Documentazione webhook: aggiunti esempi dettagliati del payload per tutti i tipi di evento webhook (consegna, conferma di lettura, messaggio in arrivo, stato campagna).
  • Risposte di errore: tutte le risposte di errore ora includono un campo path che indica l'endpoint che ha restituito l'errore.

Corretto​

  • Corretto un problema per cui valori di offset superiori a total restituivano un errore 500 invece di un array data vuoto.
  • Corretti formati di timestamp inconsistenti nelle risposte di stato delle campagne (ora tutti in formato ISO 8601 UTC).

v1.0.0 -- Febbraio 2026​

Aggiunto​

  • Messaggistica SMS:
    • POST /api/message-server/sms/send -- invia SMS utilizzando il formato universale moderno (singolo destinatario, supporto placeholder).
    • POST /api/message-server/sms/legacy/send -- invia SMS utilizzando il formato legacy (multi-destinatario in una singola richiesta).
    • Rilevamento Unicode e calcolo automatico delle parti del messaggio.
  • Messaggistica RCS:
    • POST /api/message-server/rcs/send -- invia messaggi RCS (testo, card, carosello).
    • GET /api/message-server/rcs/templates -- elenca i template RCS disponibili.
    • POST /api/message-server/rcs/templates -- crea un nuovo template RCS.
    • PUT /api/message-server/rcs/templates/{id} -- aggiorna un template RCS esistente.
    • DELETE /api/message-server/rcs/templates/{id} -- elimina un template RCS.
    • Suggerimenti interattivi: rispondi, apri URL, chiama, posizione, evento calendario.
    • Fallback automatico a WhatsApp e/o SMS quando il destinatario non supporta RCS.
  • Messaggistica WhatsApp:
    • POST /api/message-server/whatsapp/send -- invia messaggi WhatsApp (testo, immagine, video, audio, documento, posizione, sticker, reazione).
    • GET /api/message-server/whatsapp/templates -- elenca i template WhatsApp approvati.
    • GET /api/message-server/whatsapp/phone-numbers -- elenca i numeri di telefono WhatsApp registrati.
    • Messaggi template con pulsanti, header multimediali e link tracciati.
    • Fallback automatico a RCS e/o SMS.
  • Gestione Contatti e Liste:
    • GET /api/partner-gateway/v1/contacts -- elenca i contatti con ricerca e filtri.
    • POST /api/partner-gateway/v1/contacts -- crea un nuovo contatto.
    • PUT /api/partner-gateway/v1/contacts/{id} -- aggiorna un contatto.
    • DELETE /api/partner-gateway/v1/contacts/{id} -- elimina un contatto.
    • GET /api/partner-gateway/v1/lists -- elenca le liste di contatti.
    • POST /api/partner-gateway/v1/lists -- crea una nuova lista di contatti.
    • POST /api/partner-gateway/v1/lists/{id}/contacts -- aggiungi contatti a una lista.
    • DELETE /api/partner-gateway/v1/lists/{id}/contacts -- rimuovi contatti da una lista.
  • Gestione Campagne:
    • GET /api/partner-gateway/v1/campaigns -- elenca le campagne con filtro per stato.
    • POST /api/partner-gateway/v1/campaigns -- crea una nuova campagna.
    • GET /api/partner-gateway/v1/campaigns/{id} -- ottieni i dettagli della campagna e le statistiche di consegna.
    • PUT /api/partner-gateway/v1/campaigns/{id} -- aggiorna una campagna in bozza.
    • DELETE /api/partner-gateway/v1/campaigns/{id} -- elimina una campagna in bozza.
    • POST /api/partner-gateway/v1/campaigns/{id}/send -- lancia una campagna.
    • Supporto alla programmazione: invia immediatamente o a una data e ora specificate.
  • Tracciamento Consegne e Webhook:
    • GET /api/partner-gateway/v1/messages/status -- controlla lo stato di consegna del messaggio.
    • GET /api/partner-gateway/v1/webhooks -- elenca gli endpoint webhook configurati.
    • POST /api/partner-gateway/v1/webhooks -- registra un nuovo endpoint webhook.
    • PUT /api/partner-gateway/v1/webhooks/{id} -- aggiorna un endpoint webhook.
    • DELETE /api/partner-gateway/v1/webhooks/{id} -- elimina un endpoint webhook.
    • Eventi: conferma di consegna, conferma di lettura, messaggio in arrivo, campagna completata.
    • Verifica della firma HMAC per i payload webhook.
  • Sistema di Esportazione:
    • POST /api/partner-gateway/v1/exports -- richiedi un'esportazione dati asincrona (contatti o report di consegna).
    • GET /api/partner-gateway/v1/exports/{id} -- controlla lo stato dell'esportazione e il link per il download.
    • Formati di esportazione: CSV e XLSX.
  • Abbonamento e Fatturazione:
    • GET /api/partner-gateway/v1/subscription -- ottieni i dettagli del piano attuale e il saldo crediti.
  • Autenticazione: API Key (header X-Api-Key) e Basic Auth (header Authorization: Basic).
  • Rate limiting: 1.000 richieste/min per chiavi di produzione, 100 richieste/min per chiavi trial.
  • Paginazione: pattern offset/limit su tutti gli endpoint di collezione (limit predefinito: 20, massimo: 100).
Informazioni

Per domande su qualsiasi release, contatta il nostro team di supporto sviluppatori o visita le FAQ.