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:

1. Accodamento -- La richiesta POST crea un job asincrono e risponde con 202 Accepted in millisecondi.
2. Elaborazione -- Un worker in background raccoglie i dati, li formatta in CSV/EXCEL e carica il file su uno storage sicuro.
3. Notifica -- Lo status passa da PENDING a COMPLETED (o FAILED). Usa polling su GET /exports per verificare.
4. 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.
5. 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