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/contacts`, `GET /messages/history`, `POST /messages/history/export`

Scenari reali

Banca Adriatica — Report mensile per 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 performance campagna: Dopo la campagna Black Friday, il marketing esporta i report per calcolare tassi di consegna, apertura e conversione per canale.
FarmaExpress — Audit di conformita: Per requisiti GDPR, il DPO esporta lo storico completo dei messaggi inviati in un trimestre con dettaglio destinatario e contenuto.

Prerequisites

Before you begin, make sure you have:

Active API Key → How to get one
Sufficient credit → Check in the Qlara Dashboard

:::tip Test without costs Add "simulation": true in the request body to validate the flow without actually sending messages and without consuming credit. :::

Flusso di esportazione

Guida passo-passo

Step 1 — Richiedere l'export dei delivery report

Esporta i report di consegna per un intervallo di date:

curl -X POST "https://lora-api.agiletelecom.com/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

Puoi anche filtrare per campagna specifica:

curl -X POST "https://lora-api.agiletelecom.com/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 intervallo (`yyyy-MM-dd HH:mm:ss.SSSZ`)
`endDateTime`	`string`	Fine intervallo
`sender`	`string`	Filtra per mittente
`recipient`	`string`	Filtra per destinatario
`campaignId`	`integer`	ID campagna (alternativo all'intervallo date)
`sendType`	`string`	Tipo invio: `WEB`, `WEB_API`, `API`
`subAccountId`	`string`	Filtra per sub-account
`exportFormat`	`string`	Formato: `CSV` (default) o `EXCEL`

Step 2 — Elencare le esportazioni

Controlla lo stato dei tuoi export:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/exports" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

[
  {
    "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-01T08:15:00+02:00",
    "expiresAt": "2026-04-08T08:15:00+02:00",
    "isAvailableForDownload": true
  },
  {
    "id": 41,
    "type": "CONTACTS",
    "detail": {
      "listIds": [10, 11],
      "exportFormat": "CSV"
    },
    "status": "COMPLETED",
    "createdAt": "2026-03-28T14:30:00+01:00",
    "expiresAt": "2026-04-04T14:30:00+02:00",
    "isAvailableForDownload": false
  }
]

Status	Significato
`PENDING`	L'export e' in coda o in elaborazione
`COMPLETED`	Il file e' pronto per il download
`FAILED`	L'export ha avuto un errore

Step 3 — Verificare la disponibilita

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

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

Risposta: 202 Accepted -- Il link sara' rigenerato. Attendi qualche secondo e ricontrolla con GET /exports.

Step 4 — Scaricare il file

Quando lo status e' COMPLETED e isAvailableForDownload e' true:

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

Risposta:

{
  "url": "https://lora-api.agiletelecom.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://lora-api.agiletelecom.com/exports/42.csv?token=abc123def456&expires=1712570100"

Esportare i contatti

Puoi esportare anche le liste contatti:

curl -X POST "https://lora-api.agiletelecom.com/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 contatti da escludere (solo con `listIds`)
`exportFormat`	`string`	Formato: `CSV` o `EXCEL`

:::tip Esporta tutto Se non specifichi ne' listIds ne' contactIds, vengono esportati tutti i contatti del tuo account. :::

Storico messaggi

Consultare lo storico

Per consultare lo storico degli invii senza esportare, usa la paginazione:

curl -X GET "https://lora-api.agiletelecom.com/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&size=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Esportare lo storico come CSV

Per volumi elevati, esporta lo storico in modo asincrono:

curl -X POST "https://lora-api.agiletelecom.com/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

Il job di export 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 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 con 202 Accepted in millisecondi.
Elaborazione -- Un worker in background raccoglie i dati, li formatta in CSV/EXCEL e carica il file su uno storage sicuro.
Notifica -- Lo status passa da PENDING a COMPLETED (o FAILED). Usa polling su GET /exports per verificare.
Download -- L'URL di download e' un link pre-firmato con scadenza temporale. Dopo la scadenza, puoi rigenerarlo con POST /exports/{exportId} senza rielaborare i dati.
Retention -- Gli export rimangono disponibili per un periodo limitato (tipicamente 7 giorni). Dopo la scadenza, il file viene rimosso ma i parametri originali sono conservati per la rigenerazione.

Expected result

Aspect	Detail
Action completed	Delivery reports or contacts exported as CSV/Excel file
Channel used	All (SMS, RCS, WhatsApp)
Delivery confirmation	Export status changes from `PENDING` to `COMPLETED`; download URL available

Common errors

Problem	Probable cause	Solution
HTTP `401`	Missing or invalid API Key	Check `X-Api-Key` header
`accepted: false`	Insufficient credit or invalid number	Check credit; verify E.164 format
Export `FAILED` — Date range too large	Range exceeds 90 days	Split into multiple exports with smaller date ranges
`isAvailableForDownload: false`	Download link has expired	Regenerate the link with `POST /exports/{exportId}`
Empty CSV	No messages found for the specified filters	Verify date range, channel, and campaign ID filters

Prossimi passi

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

Scenari reali​

Prerequisites​

Flusso di esportazione​

Guida passo-passo​

Step 1 — Richiedere l'export dei delivery report​

Step 2 — Elencare le esportazioni​

Step 3 — Verificare la disponibilita​

Step 4 — Scaricare il file​

Esportare i contatti​

Storico messaggi​

Consultare lo storico​

Esportare lo storico come CSV​

Riepilogo endpoint​

Expected result​

Common errors​

Prossimi passi​

Scenari reali

Prerequisites

Flusso di esportazione

Guida passo-passo

Step 1 — Richiedere l'export dei delivery report

Step 2 — Elencare le esportazioni

Step 3 — Verificare la disponibilita

Step 4 — Scaricare il file

Esportare i contatti

Storico messaggi

Consultare lo storico

Esportare lo storico come CSV

Riepilogo endpoint

Expected result

Common errors

Prossimi passi