Guida: gestire i clienti

In preparazione. Struttura prevista (modello del capitolo Accessi).

Obiettivo — Censire e mantenere l'anagrafica dei clienti (azienda, persona fisica, ditta individuale).

Contenuti previsti

• Le tre tipologie di cliente e i dati richiesti per ciascuna.
• Creare un nuovo cliente: passi e dati minimi.
• Controlli automatici anti-duplicato (codice fiscale / partita IVA).
• Aggiornare e disattivare un cliente (stati: lead, attivo, sospeso, cessato).
• Cosa succede eliminando un cliente collegato a contratti o forniture.

Indirizzo obbligatorio

Un cliente non può essere creato senza almeno un indirizzo: la creazione richiede sempre un blocco indirizzi con almeno una voce valorizzata (campo indirizzo). Senza, l'API risponde 400.

La creazione è inoltre atomica: cliente, anagrafica e indirizzi vengono scritti in un'unica transazione. Se un indirizzo è invalido (es. tipo fuori dai valori ammessi), non viene creato alcun cliente (niente record "orfani"): l'API risponde 400 e non lascia nulla a metà.

Tipologie di cliente

Il campo tipo determina quali dati anagrafici sono richiesti:

tipo	Blocco payload	Dati principali
AZIENDA	azienda	ragione_sociale (obbligatoria), codice_fiscale, partita_iva, codice_ateco, tipo_societa
CONDOMINIO	azienda	ragione_sociale (obbligatoria), codice_fiscale
PUBBLICA_ADMIN	azienda	ragione_sociale (obbligatoria), codice_fiscale
ALTRI_ENTI	azienda	ragione_sociale (obbligatoria), codice_fiscale
PERSONA_FISICA	persona_fisica	nome + cognome (obbligatori), codice_fiscale, dati di nascita
DITTA_INDIVIDUALE	ditta_individuale	ragione_sociale (obbligatoria: denominazione/insegna), codice_fiscale e partita_iva (obbligatori), nome + cognome del titolare (facoltativi), dati di nascita

AZIENDA, CONDOMINIO, PUBBLICA_ADMIN, ALTRI_ENTI sono tutte persone giuridiche: usano lo stesso blocco azienda del payload (in creazione, modifica e lettura). Cambia solo il tipo.

Per la ditta individuale il campo ragione_sociale (denominazione/insegna) è obbligatorio, mentre nome e cognome del titolare sono facoltativi. Tutti nel blocco ditta_individuale.

Codice cliente

Ogni cliente può avere un codice_cliente: un identificativo di business scelto dal tenant (es. CLI-000123), distinto dall'id interno assegnato dal sistema (C…). È facoltativo, si valorizza in creazione e in modifica, ed è univoco all'interno del tenant: due clienti dello stesso ambiente non possono avere lo stesso codice (un doppione restituisce 409 codice_cliente_already_exists). È anche uno dei campi su cui agisce la ricerca ?q=.

curl -X POST https://api.base9.app/v1/clienti \
  -H "Authorization: Bearer dmk_..." -H "Content-Type: application/json" \
  -d '{ "tipo":"AZIENDA", "azienda":{"ragione_sociale":"ESEMPIO SRL","partita_iva":"01234567890"}, "codice_cliente":"CLI-000123" }'

Campi di supporto per migrazioni/import

Quando i clienti provengono da un'altra applicazione (un gestionale legacy, un export CSV, ecc.) è utile conservare il riferimento all'origine, così da poter riconciliare i record e rifare gli import senza creare duplicati. Per questo ogni cliente ha due campi facoltativi:

Campo	Significato
origine_esterna	sistema di provenienza (es. gestionale_x, legacy_mysql)
id_esterno	identificativo del cliente nel sistema di origine

Sono campi normali dell'anagrafica: si valorizzano in creazione e in modifica, e vengono restituiti quando si legge il cliente.

# creazione con riferimento esterno
curl -X POST https://api.base9.app/v1/clienti \
  -H "Authorization: Bearer dmk_..." -H "Content-Type: application/json" \
  -d '{
        "tipo": "AZIENDA",
        "azienda": { "ragione_sociale": "ESEMPIO SRL", "partita_iva": "01234567890" },
        "origine_esterna": "gestionale_legacy",
        "id_esterno": "44718"
      }'

De-duplicazione automatica. La coppia (origine_esterna, id_esterno) è unica all'interno del tenant: se provi a creare un secondo cliente con lo stesso riferimento, l'API risponde 409 con codice riferimento_esterno_already_exists. Questo rende gli import idempotenti: puoi rilanciare una migrazione e i record già presenti non verranno duplicati. I clienti senza provenienza esterna (campi vuoti) non sono soggetti al vincolo.

Suggerimento: durante una migrazione, prima di creare cerca il cliente per riferimento esterno; se esiste, usa la modifica (PUT) invece della creazione.

Riferimento tecnico — API Reference, sezione Clienti (campi origine_esterna / id_esterno sullo schema Cliente).