Exports de données CSV · Parquet · JSON Schema

Trois formats d'export documentés : CSV pour tableurs et analyses ad-hoc, Parquet pour pipelines analytics, JSON Schema pour intégrations typées. Export via l'UI admin ou l'API REST.

Formats disponibles

CSV

Séparateur virgule, UTF-8 BOM, ligne d'en-têtes.

  • Compatible Excel / LibreOffice
  • Streaming, pas de limite de lignes
  • Portabilité RGPD art.20

Parquet

Format colonnaire, compression Snappy, compatible Arrow.

  • DuckDB / pandas / Spark
  • 5 à 10× plus petit que CSV
  • Recommandé > 1M lignes

JSON Schema

JSON Schema draft 2020-12 + records signés.

  • Intégration typée
  • Génération types TypeScript / Python
  • Versionné, rétrocompatible

Export via l'UI admin

  1. 1

    Aller sur Data → Exports

    Accessible aux rôles admin et auditor.

  2. 2

    Choisir un dataset

    CDR bruts, KPIs agrégés, journal d'audit, configuration agent.

  3. 3

    Filtrer et choisir le format

    Filtres plage de dates, PBX, sens, ligne téléphonique + dropdown format (CSV / Parquet / JSON).

  4. 4

    Télécharger ou déclencher un job async

    Les exports < 10 Mo streament directement. Les plus gros tournent en job background, avec notification email à la fin.

Export via l'API REST

CSV — synchrone

curl -H "Authorization: Bearer <token>" \
  "https://<vm>:8443/api/v1/cdr/export?from=2026-01-01&to=2026-01-31&format=csv" \
  -o cdr-2026-01.csv

Parquet — job async

# 1. Submit the job
curl -X POST -H "Authorization: Bearer <token>" \
  -d '{"from":"2025-01-01","to":"2025-12-31","format":"parquet"}' \
  https://<vm>:8443/api/v1/cdr/export-jobs

# 2. Poll the job
curl -H "Authorization: Bearer <token>" \
  https://<vm>:8443/api/v1/cdr/export-jobs/<job-id>

# 3. Download via the signed URL returned when status=ready

JSON Schema

curl https://<vm>:8443/api/v1/schemas/cdr.json
# Returns a JSON Schema draft 2020-12 document describing the CDR record format.

Schéma CDR (extrait)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://getnatalia.com/schemas/cdr/v1.json",
  "title": "Natalia CDR Record",
  "type": "object",
  "required": ["id", "pbx_alias", "start_at", "duration_s", "direction"],
  "properties": {
    "id":           { "type": "string", "format": "uuid" },
    "pbx_alias":    { "type": "string" },
    "start_at":     { "type": "string", "format": "date-time" },
    "duration_s":   { "type": "integer", "minimum": 0 },
    "direction":    { "enum": ["inbound", "outbound", "internal"] },
    "calling_party":{ "type": "string", "description": "pseudonymised hash for external numbers" },
    "called_party": { "type": "string" },
    "trunk":        { "type": "string" },
    "extension":    { "type": "string" },
    "result":       { "enum": ["answered", "no-answer", "busy", "abandoned"] }
  }
}

Le schéma est versionné (v1, v2…) et reste rétrocompatible : un nouveau champ est toujours ajouté, jamais remplacé. Les changements breaking passent par un major bump avec une fenêtre de migration de 12 mois.

À la recherche de la réversibilité ?

Les procédures d'export ci-dessus couvrent aussi la portabilité RGPD art.20 et la restitution de fin de contrat sous 30 jours.

Procédure de réversibilité