UC-011 — Export Report di Consegna e Storico

Campo	Valore
ID	UC-011
Obiettivo	Esportare delivery report, storico messaggi e contatti in CSV
Canale	Tutti (SMS, RCS, WhatsApp)
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	15 minuti
API coinvolte	`POST /api/partner-gateway/v1/exports/delivery-reports`, `GET /exports`, `GET /exports/{exportId}`, `POST /exports/{exportId}`, `POST /exports/contacts`, `GET /messages/history`, `POST /messages/history/export`

Scenari reali

Banca Adriatica — Report mensile per la fatturazione: Ogni primo del mese il team finance esporta tutti i delivery report del mese precedente per riconciliare i costi di invio SMS e WhatsApp.
FashionOutlet — Analisi delle performance di campagna: Dopo la campagna del Black Friday, il marketing esporta i report per calcolare tassi di consegna, apertura e conversione per canale.
FarmaExpress — Audit di conformità: Per i requisiti GDPR, il DPO esporta lo storico completo dei messaggi inviati in un trimestre, con il dettaglio dei destinatari.

Prerequisiti

Prima di iniziare, assicurati di avere:

API Key attiva → Come ottenerla
Messaggi da esportare → messaggi inviati nel periodo da analizzare, oppure un campaignId

Flusso di esportazione

Guida passo-passo

Step 1 — Richiedere l'export dei delivery report

Esporta i report di consegna per un intervallo di date. Le date usano il formato yyyy-MM-dd HH:mm:ss.SSSZ:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/exports/delivery-reports" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDateTime": "2026-03-01 00:00:00.000+0100",
    "endDateTime": "2026-03-31 23:59:59.000+0200",
    "sendType": "API",
    "exportFormat": "CSV"
  }'

Risposta: 202 Accepted -- il job di export è in coda.

Puoi anche esportare una campagna specifica invece di un intervallo di date:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/exports/delivery-reports" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": 1584,
    "exportFormat": "CSV"
  }'

Parametro	Tipo	Descrizione
`startDateTime`	`string`	Inizio dell'intervallo (`yyyy-MM-dd HH:mm:ss.SSSZ`)
`endDateTime`	`string`	Fine dell'intervallo
`sender`	`string`	Filtra per mittente
`recipient`	`string`	Filtra per destinatario
`campaignId`	`integer`	ID campagna (alternativo all'intervallo di date)
`sendType`	`string`	Tipo di invio: `WEB`, `WEB_API`, `API`
`subAccountId`	`string`	Filtra per sub-account
`exportFormat`	`string`	Formato: `CSV` (default) o `EXCEL`

Una richiesta senza campaignId né intervallo di date, o con una data nel formato sbagliato, riceve 400.

Step 2 — Elencare le esportazioni

Controlla lo stato dei tuoi export. La lista è paginata con page (da 0) e limit (default 10):

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/exports?page=0&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "data": [
    {
      "id": 42,
      "type": "DELIVERY_REPORT",
      "detail": {
        "startDateTime": "2026-03-01T00:00:00+01:00",
        "endDateTime": "2026-03-31T23:59:59+02:00",
        "sendType": "API",
        "exportFormat": "CSV"
      },
      "status": "COMPLETED",
      "createdAt": "2026-04-01 08:15:00.000+0200",
      "expiresAt": "2026-04-08 08:15:00.000+0200",
      "isAvailableForDownload": true
    },
    {
      "id": 41,
      "type": "CONTACTS",
      "detail": {
        "listIds": [10, 11],
        "exportFormat": "CSV"
      },
      "status": "COMPLETED",
      "createdAt": "2026-03-28 14:30:00.000+0100",
      "expiresAt": "2026-04-04 14:30:00.000+0200",
      "isAvailableForDownload": false
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 2,
  "totalPages": 1
}

Status	Significato
`PENDING`	L'export è in coda o in elaborazione
`COMPLETED`	Il file è pronto per il download
`FAILED`	L'export si è concluso con un errore

Step 3 — Verificare la disponibilità

Prima di scaricare, controlla che isAvailableForDownload sia true. Se il link è scaduto (isAvailableForDownload: false), rigeneralo:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/exports/41" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta: 202 Accepted -- il link verrà rigenerato. Attendi qualche secondo e ricontrolla con GET /exports. Un export non ancora scaduto riceve 400 (basta scaricarlo), un exportId sconosciuto 404.

Step 4 — Scaricare il file

Quando lo status è COMPLETED e isAvailableForDownload è true:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/exports/42" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "url": "https://storage.example.com/exports/42.csv?token=abc123def456&expires=1712570100"
}

Usa l'URL restituito per scaricare il file CSV:

curl -o delivery-report-marzo-2026.csv "https://storage.example.com/exports/42.csv?token=abc123def456&expires=1712570100"

Esportare i contatti

Puoi esportare anche le liste contatti:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/exports/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "listIds": [10, 11],
    "exportFormat": "CSV"
  }'

Risposta: 202 Accepted

Parametro	Tipo	Descrizione
`listIds`	`array[int]`	ID delle liste da esportare (alternativo a `contactIds`)
`contactIds`	`array[int]`	ID dei contatti specifici da esportare
`excludeContactIds`	`array[int]`	ID dei contatti da escludere (solo con `listIds`)
`exportFormat`	`string`	Formato: `CSV` o `EXCEL`

Esporta tutto

Se non specifichi né listIds né contactIds, vengono esportati tutti i contatti del tuo account.

Storico messaggi

Consultare lo storico

Per consultare lo storico degli invii senza esportarlo, usa la paginazione. channel, from e to sono obbligatori:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/messages/history?channel=SMS&from=2026-03-01T00:00:00%2B01:00&to=2026-03-31T23:59:59%2B02:00&page=0&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Esportare lo storico come CSV

Per volumi elevati, esporta lo storico in modo asincrono. Le date sono ISO 8601 con offset; sender e recipient sono filtri opzionali:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/messages/history/export" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDateTime": "2026-03-01T00:00:00+01:00",
    "endDateTime": "2026-03-31T23:59:59+02:00",
    "sender": "TechStore",
    "recipient": "+393471234567"
  }'

Risposta: 202 Accepted con corpo vuoto.

L'export copre tutti i canali (SMS, RCS, WhatsApp) e solo i messaggi inviati tramite API; non ha filtri per canale o per stato. Il job segue lo stesso flusso: controlla GET /exports e scarica con GET /exports/{exportId}.

Riepilogo endpoint

Azione	Metodo	Endpoint
Export delivery report	`POST`	`/exports/delivery-reports`
Export contatti	`POST`	`/exports/contacts`
Export storico messaggi	`POST`	`/messages/history/export`
Lista esportazioni	`GET`	`/exports`
URL di download	`GET`	`/exports/{exportId}`
Rigenera link scaduto	`POST`	`/exports/{exportId}`
Consulta storico	`GET`	`/messages/history`

Dietro le quinte

Le esportazioni sono progettate per gestire grandi volumi di dati senza bloccare l'API:

Accodamento -- La richiesta POST crea un job asincrono e risponde 202 Accepted in pochi millisecondi.
Elaborazione -- Un worker in background raccoglie i dati, li formatta in CSV/EXCEL e carica il file su uno storage sicuro.
Stato -- Lo status passa da PENDING a COMPLETED (o FAILED). Interroga GET /exports per verificarlo.
Download -- L'URL di download è un link pre-firmato con scadenza. Una volta scaduto, puoi rigenerarlo con POST /exports/{exportId} senza inviare di nuovo la richiesta.
Conservazione -- Gli export restano disponibili fino a expiresAt (in genere 7 giorni). Dopo, il file viene rimosso, ma i parametri originali vengono conservati per la rigenerazione.

Risultato atteso

Aspetto	Dettaglio
Azione completata	Delivery report, storico messaggi o contatti esportati in un file CSV/Excel
Canale usato	Tutti (SMS, RCS, WhatsApp)
Conferma	Lo status dell'export passa da `PENDING` a `COMPLETED`; URL di download disponibile

Errori comuni

Problema	Causa probabile	Soluzione
HTTP `401`	API Key mancante o non valida	Controlla l'header `X-Api-Key`
HTTP `400` sulla richiesta di export	Né `campaignId` né intervallo di date, oppure una data nel formato sbagliato	Passa `campaignId` oppure `startDateTime`/`endDateTime` (`yyyy-MM-dd HH:mm:ss.SSSZ` per i delivery report, ISO 8601 con offset per l'export dello storico)
Export `FAILED`	Il job in background si è concluso con un errore	Richiedi di nuovo l'export; se fallisce ancora, contatta il supporto indicando l'`X-Request-Id` della richiesta
`isAvailableForDownload: false` o HTTP `400` su `GET /exports/{exportId}`	Il link di download è scaduto	Rigenera il link con `POST /exports/{exportId}`
HTTP `404` su `/exports/{exportId}`	`exportId` errato o export di un altro account	Prendi l'`id` da `GET /exports`
CSV vuoto	Nessun messaggio trovato con i filtri indicati	Verifica l'intervallo di date e i filtri `campaignId`, `sender` e `recipient`

Prossimi passi

Guida Exports -- Panoramica completa del sistema di export
Guida Contatti e Liste -- Gestione di contatti e liste
Guida Webhooks -- Configura i webhook per il tracking in tempo reale
UC-010: Invio Programmato -- Programma gli invii e poi esporta i report

Scenari reali​

Prerequisiti​

Flusso di esportazione​

Guida passo-passo​

Step 1 — Richiedere l'export dei delivery report​

Step 2 — Elencare le esportazioni​

Step 3 — Verificare la disponibilità​

Step 4 — Scaricare il file​

Esportare i contatti​

Storico messaggi​

Consultare lo storico​

Esportare lo storico come CSV​

Riepilogo endpoint​

Risultato atteso​

Errori comuni​

Prossimi passi​