Appearance

Unified endpoints for metering, billing and customer self-service.

API Reference ↗
Manuale BASE9 →
Base9 — Serverless Energy APIBase9 — Serverless Energy API
📘

Manuale BASE9

Guida all'integrazione descrittiva per partner e referenti di progetto — concetti, scenari e procedure passo-passo, complementare all'API Reference.

Apri il Manuale

🏗️

Architettura tecnica

Come sono fatti i dati e come ci si arriva — i due archivi, i quattro controlli sulla correttezza, l'isolamento fra clienti, la recuperabilità.

Vedi l'architettura

🧾

Fatturazione e bollettazione

Dalle misure validate al documento — righe, emissione, incassi, scadenzario. Le regole si configurano per contratto e gruppo di fatturazione; la bolletta segue la struttura prevista da ARERA.

Come funziona

🪪

Area riservata

Accessi separati per cliente finale e per rete agenti, con permessi distinti e aspetto personalizzabile. Consumi, documenti e posizione contabile visibili a chi ne ha diritto, con l'incasso online innestabile sul gateway di pagamento scelto.

Vedi un esempio completo

🔌

API-first

Tutta la piattaforma è esposta via REST API. Pattern Stripe-style con envelope, errori strutturati, cursor pagination, ISO 8601 UTC.

🏢

Multi-tenant

Architettura database-per-tenant. Isolamento dei dati nella struttura, non in una clausola che si può dimenticare. Capacità elastica per singolo cliente.

⚡

POD · PDR · REMI

Tre anagrafiche distinte per le commodity energia (elettrico + gas distribuzione + gas trasporto). Dati tecnici storicizzati.

📄

CGF · CTE

Modello a tre livelli — contratto cliente (CGF), gruppi di fatturazione, condizioni tecnico-economiche per singolo punto (CTE).

🔐

Auth flessibile

Sessioni JWT per il pannello, API key (dmk_*) per chi integra dall'esterno. Ambito di lettura o scrittura per singola chiave.

📡

Telco extension

TELCO_VOCE / TELCO_DATI / FIBRA come tipi di punto fornitura. Stesso modello CGF/CTE applicato.

Documentazione ​

Due livelli complementari:

DocumentoCosa offrePer chi
📘 Manuale BASE9Guida descrittiva: concetti, scenari, procedurePartner, referenti di progetto
⚡ API ReferenceRiferimento tecnico interattivo (try-it-out) + spec OpenAPI 3.1 (JSON/YAML)Sviluppatori

Il riferimento tecnico degli endpoint è l'API Reference (OpenAPI 3.1 + UI interattiva). La spec machine-readable è su openapi.json / openapi.yaml.

Versioni disponibili ​

VersioneStatoReleasedLink
v1Current2026-05-10→ API Reference

Base URL ​

https://api.base9.app

Risorse principali ​

RisorsaEndpoint baseDescrizione
Clienti/v1/clientiAnagrafica clienti (PF/PG, indirizzi, contatti, legali rappresentanti)
Punti di fornitura/v1/punti_fornituraPOD elettrico (14 alfanumerici), PDR gas distribuzione (14 numerici), REMI gas trasporto, telco
Dati tecnici/v1/punti_fornitura/{id}/dati_tecniciStoria tecnica del punto (tensione, potenza, classe misuratore, opzione ARERA, ecc.). Schema differente per commodity.
Contratti (CGF)/v1/contrattiCondizioni Generali di Fornitura — documento commerciale firmato dal cliente. Multi-commodity. Codice auto CGF-YYYY-NNNNNN.
Gruppi fatturazione/v1/contratti/{id}/gruppiLivello intermedio CGF → CTE. Multisito, periodo fatturazione, raggruppamento bolletta.
CTE/v1/cteCondizioni Tecnico-Economiche per singolo punto. Codice auto CTE-YYYY-NNNNNN. Storicizzate.
Intestazioni/v1/clienti/{id}/intestazioni, /v1/intestazioni/{id}Relazione storicizzata cliente↔POD. PATCH per correzioni, domain action per voltura/switching/cessazione.

Quick start ​

Gli esempi usano una API key (Authorization: Bearer dmk_..., scope r/rw per tenant). Per l'accesso utente/frontend usa invece un JWT e seleziona il tenant con l'header X-Tenant-Id. Ogni endpoint è provabile dal vivo nell'API Reference (try-it-out).

1 · Crea un cliente

bash
curl -X POST https://api.base9.app/v1/clienti \
  -H "Authorization: Bearer dmk_xxxx" -H "Content-Type: application/json" \
  -d '{
    "tipo": "AZIENDA",
    "azienda": { "ragione_sociale": "ESEMPIO SRL", "partita_iva": "01234567890" }
  }'
# → 201  { "object": "cliente", "id": "C8F6189ED", "request_id": "req_…", "data": { … } }

2 · Rileggi il cliente e scorri la lista (paginazione a cursore)

bash
curl -H "Authorization: Bearer dmk_xxxx" \
  https://api.base9.app/v1/clienti/C8F6189ED

curl -H "Authorization: Bearer dmk_xxxx" \
  "https://api.base9.app/v1/clienti?limit=25&starting_after=C8F6189ED"

3 · Onboarding in una sola call — POST /v1/contratti con punto_fornitura_id crea in cascata CGF + gruppo Default + CTE

bash
curl -X POST https://api.base9.app/v1/contratti \
  -H "Authorization: Bearer dmk_xxxx" -H "Content-Type: application/json" \
  -d '{
    "cliente_id":         "C8F6189ED",
    "data_firma":         "2026-05-13",
    "modalita_firma":     "OTP",
    "data_inizio":        "2026-05-13",
    "punto_fornitura_id": 100,
    "cte": { "esecuzione_anticipata": false }
  }'

4 · Domain action: voltura di un POD

bash
curl -X POST https://api.base9.app/v1/punti_fornitura/38/voltura \
  -H "Authorization: Bearer dmk_xxxx" -H "Content-Type: application/json" \
  -d '{ "cliente_id_nuovo": "CF5159EF0", "data": "2026-06-01" }'

Convenzioni trasversali (envelope, errori, paginazione, soft-delete, limiti) in cima all'API Reference.

Vedi il Manuale BASE9 per la guida all'integrazione e l'API Reference per il dettaglio tecnico di endpoint, body, errori.

BASE9 è costruito interamente su Amazon Web Services: infrastruttura serverless, cifratura a riposo, isolamento dei dati per cliente. Vedi l'architettura →