---
title: "Come imposta una numerazione dei documenti che resista alla produzione?"
blueprint: 006
slug: document-numbering-that-survives-production
category: Numerazione
published: 2026-09-23
revised: 2026-09-23
platform: Coevera CRM (formerly Pipeliner CRM)
canonical: https://blueprints.coevera.com/it/blueprints/document-numbering-that-survives-production/
language: it
translation_of: https://blueprints.coevera.com/blueprints/document-numbering-that-survives-production/
author: Lucia Schmidt
publisher: Coevera
customer_data: none
---

# Come imposta una numerazione dei documenti che resista alla produzione?

**Risposta breve.** Usi un campo **Auto number**. Il suo pattern è un costruttore di segmenti —
testo letterale, un token **Year (YYYY)**, un **Autocount** — e il segmento Autocount prevede un
pulsante di opzione per **"Reset count every year"** contrapposto a "Don't reset count".
L'azzeramento annuale è un'opzione nativa, e non serve alcuna automazione. Il ritorno del
conteggio a 1 a un reale cambio d'anno non è stato osservato (si veda §7).

**Se in seguito cambia il pattern tramite l'API, ometta il numero finale.** Il centro assistenza
non descrive questa via; secondo il centro assistenza le opzioni non si possono modificare dopo
**Save**. Il `,1` in `{#Number4,1}` è un **indice iniziale**, non una decorazione: dice *iniziare
questa serie da 1*, e fa esattamente questo ogni volta che viene inviato — anche su un campo che
emette numeri da due anni. Scriva `{#Number4}` e il conteggio prosegue da dove era arrivato.

## 01 · Il problema di business

Un documento aziendale ha bisogno di un riferimento destinato alle persone — un numero di fattura,
un numero di pratica, un numero di documento che compare sui documenti cartacei e viene citato
nelle email e nelle telefonate. I requisiti sono poco affascinanti e rigorosi:

- **Univoco**, per sempre. Due documenti con lo stesso numero non sono un problema estetico.
- **Leggibile e pronunciabile** — una persona lo legge ad alta voce al telefono.
- **Legato all'anno**, nella maggior parte delle giurisdizioni e delle prassi contabili: la
  sequenza riparte ogni gennaio, così il numero porta con sé il proprio periodo.
- **Stabile** — una volta emesso non cambia mai, perché è stampato su documenti che hanno già
  lasciato l'azienda.

In ambito contabile non si tratta di una semplice convenzione. Una serie di numeri di documento
che ripete un valore è un rilievo di audit, e in diverse giurisdizioni un problema di conformità
anziché un semplice inconveniente.

## 02 · Perché l'approccio ovvio non funziona

### Costruire il numero da sé, perché le è stato detto che era necessario

> **Troverà consigli secondo cui deve costruire il numero da sé.** Affermano che i campi sequenza
> non possono azzerarsi ogni anno, e che un numero di documento con prefisso dell'anno deve quindi
> essere composto in un processo di automazione — un semplice contatore per il numero progressivo
> e un processo che vi concatena l'anno.
>
> Quel consiglio è **sbagliato**, ed è ripetuto abbastanza spesso da meritare di essere nominato.
> La piattaforma ha un'opzione esplicita "Reset count every year" integrata nell'editor del
> pattern. Prima di costruire un processo di composizione, apra l'editor del campo e guardi.

Vale la pena essere concreti su quanto costa l'espediente superfluo, perché lo stesso ragionamento
vale ogni volta che si sostituisce un meccanismo nativo con un'automazione:

- **Una seconda fonte di verità.** Il contatore reale e il campo di testo composto possono
  divergere, e nulla li riconcilia.
- **Una race condition.** Due record creati nello stesso istante possono essere composti con lo
  stesso numero, perché non è la composizione a garantire l'univocità.
- **Una modalità di errore senza alcun segnale.** Se il processo è disattivato, fallisce o viene
  escluso da un filtro, i record vengono creati con un numero di documento vuoto e nessuno se ne
  accorge finché qualcuno non va a guardare.
- **Manutenzione continua** di una logica che la piattaforma avrebbe mantenuto al posto suo.

### Usare l'identificatore del record

Tecnicamente univoco, e inutile. È un UUID: non leggibile, non pronunciabile, non legato all'anno,
e a un cliente non dice nulla.

## 03 · Il costruttore di pattern

Nell'interfaccia il tipo di campo si chiama **Auto number**. Il suo pattern viene assemblato da
segmenti ordinati anziché digitato come stringa:

| Segmento | Scopo |
|---|---|
| **Text** | Un prefisso o separatore letterale — un codice del tipo di documento, l'iniziale di un'azienda. |
| **Year (YYYY)** | L'anno a quattro cifre, risolto al momento della creazione del record. |
| **Autocount** | Il numero progressivo, con il suo numero di cifre. **È questo segmento a contenere la scelta di azzeramento.** |
| **Text** | Altri segmenti letterali, prima o dopo uno qualsiasi dei precedenti. |

Sul segmento Autocount si trovano due opzioni che si escludono a vicenda: **Reset count every
year** e **Don't reset count**. Quell'unico pulsante di opzione è la risposta alla domanda che dà
il nome a questo blueprint.

Durante la costruzione l'editor mostra un esempio in tempo reale del valore successivo — `Example:
TST20260004` — utile in fase di configurazione. Lo tratti come un controllo della formattazione,
non come una prova sul contatore; solo un record creato può dirle quello.

## 04 · Configurazione e forma nell'API

### Crearne uno in modo programmatico

Il pattern è espresso come stringa di token, e il campo contiene un oggetto `sequence`:

```
sequence: {
  defaultItem: { pattern: "TST{#Year}{#Number4,1}" },
  items: []
}
```

Primo record generato da quel pattern: `TST20260001`. Il conteggio a quattro cifre è stato
accettato tramite l'API; per un pattern impostato nell'interfaccia, il centro assistenza indica
per il numero un minimo di cinque cifre.

> **La forma di creazione e la forma di lettura differiscono.** Il `,1` è l'*indice iniziale* —
> «iniziare questa serie da 1» — e viene rimosso dalla normalizzazione una volta pubblicato il
> campo, per cui rileggendo il campo si ottiene la forma ripulita `{#Number4}`.
>
> **Questa è la regola per cambiare un pattern in seguito tramite l'API: lo invii senza il numero
> finale.** Il centro assistenza non descrive questa via; secondo il centro assistenza le opzioni
> non si possono modificare dopo **Save**. L'indice iniziale è un'istruzione, e viene eseguito
> ogni volta che arriva. Cambi `TST{#Year}{#Number4,1}` in `INV{#Year}{#Number4,1}` — una modifica
> del prefisso, apparentemente innocua — e la serie riparte da 1, riemettendo numeri già
> assegnati. Lo cambi in `INV{#Year}{#Number4}` e il contatore prosegue intatto.
>
> La procedura sicura, e il motivo per cui le due forme differiscono: **legga il campo, ne prenda
> il `pattern` alla lettera, cambi solo ciò che intendeva cambiare e lo rimandi così.** Ciò che il
> campo restituisce è già normalizzato, quindi non contiene mai un indice iniziale. Se genera i
> payload da un modello memorizzato anziché da una lettura, rimuova `,<n>` dal token del conteggio
> per qualunque campo che non sia nuovo di zecca.

> **Due trappole dell'API in fase di creazione.** Una proprietà `sequence_pattern` sull'endpoint
> REST dei campi è **deprecata** — l'API la rifiuta con un messaggio che indica di usare invece la
> proprietà `sequence`. Ma inviare il nuovo oggetto `sequence` tramite lo stesso endpoint REST
> restituisce un **500**. Creare il campo tramite l'API di amministrazione ha funzionato; il
> percorso REST no.

### Il contatore è uno stato in tre parti

Il campo espone il proprio contatore come `last_particle`, che non è un singolo intero:

```
last_particle: { year: 2026, month: 0, sequence_number: 2 }
```

Ne seguono due cose. La **componente del mese resta a zero** quando il pattern non contiene un
token del mese, quindi la sua presenza non implica un comportamento mensile. E la **componente
dell'anno è il meccanismo alla base dell'azzeramento annuale** — il motore memorizza l'anno a cui
appartiene il conteggio, ed è questo che gli permette di riconoscere un nuovo anno e ripartire.

### Contatori segmentati

L'array `items` accanto a `defaultItem` accetta voci che hanno ciascuna il proprio `pattern` *e il
proprio filtro*. È la forma di un meccanismo per più contatori indipendenti su un solo campo,
selezionati da una condizione sul record — una serie separata per tipo di documento o per unità
organizzativa.

La sua semantica non è verificata — veda il §6.

## 05 · Quando serve ancora l'automazione

Nella maggior parte dei casi non serve, ed è questo il senso del §2. C'è un solo caso reale in cui
il campo nativo non può fare il lavoro.

**Il token Year si risolve dalla creazione del record.** Se l'anno del suo numero di documento
deve provenire da una *data diversa* — una data di fattura, una data del documento, un periodo di
servizio che può cadere in un anno diverso da quello in cui il record è stato inserito — il campo
Auto number non può esprimerlo. Inoltre il contatore avanza in ordine di creazione, non
nell'ordine di quella data.

Lì, e solo lì, l'approccio per composizione è corretto: un Auto number nativo che fornisce la
parte progressiva con univocità garantita, e un processo che assembla il numero di documento
visibile dall'anno della data scelta più quel numero. Accetti esplicitamente che l'ordine di
creazione e l'ordine per data del documento possano allora divergere, e decida in anticipo quale
dei due l'azienda considera quello che fa fede — è una domanda a cui è molto più facile rispondere
prima del go-live che dopo. È anche un processo in più da gestire, quindi lo costruisca secondo le
convenzioni del [Blueprint 011, su come mantenere gestibili le
automazioni](https://blueprints.coevera.com/it/blueprints/keeping-hundreds-of-automations-maintainable/).

## 06 · Limiti e compromessi

### Una numerazione senza buchi non è ottenibile

Un numero viene emesso quando il record viene creato. Se crea un record e lo elimina, il numero è
consumato — la serie presenta un buco, e nessuna configurazione lo impedisce. Se la sua
giurisdizione o il suo revisore richiede una serie ininterrotta, sollevi la questione prima del
go-live, perché la risposta sarà una procedura di riconciliazione e non un'impostazione.

**Fonte.** Centro assistenza di Coevera, [Advanced fields & forms — Autonumber
fields](https://help.coevera.com/en/articles/5994978-advanced-fields-forms-autonumber-fields): «un
nuovo numero viene generato ogni volta che si salva un nuovo record. Un numero automatico non può
essere attivato per popolarsi quando una Opportunity viene spostata, per esempio, ma solo alla
creazione del record.»

### L'anno proviene dalla data di creazione, e solo da lì

Il token Year si risolve al momento della creazione del record, e il conteggio avanza in ordine di
creazione. Un numero il cui anno deve provenire da una data diversa — una data di fattura, una
data del documento, un periodo di servizio — non può essere espresso dal campo, e il §5 descrive
la composizione che serve al suo posto. La conseguenza da decidere fin dall'inizio è che l'ordine
di creazione e l'ordine per data del documento possono allora non coincidere.

Una serie condivisa tra diversi tipi di record è il motivo abituale per cui un singolo campo deve
reggere l'intero carico — veda il [Blueprint 001, in cui cinque tipi di richiesta passano per
un'unica serie di numeri di
riferimento](https://blueprints.coevera.com/it/blueprints/one-entity-five-request-types/).

### Più contatori su un solo campo non sono verificati

L'array `items` descritto nel §4 ha la forma di un meccanismo per serie indipendenti su un solo
campo. **Non l'abbiamo testato**, e lo diciamo anziché descrivere un comportamento che non abbiamo
osservato. Consideri una serie per tipo o per unità un rischio di progettazione finché non l'avrà
vista funzionare.

### Altre cose da sapere

- **Il conteggio riportato dall'operazione di pubblicazione non è un segnale di successo.** Nei
  nostri test ha restituito zero a ogni chiamata, pur pubblicando effettivamente.
- **I campi creati non risultano pubblicati in modo coerente.** La stessa identica chiamata di
  creazione ha restituito una volta un campo già pubblicato e un'altra volta una bozza non
  pubblicata. Controlli lo stato di pubblicazione; non lo dia per scontato.

## 07 · Verifica

La numerazione è una di quelle funzionalità che sembrano corrette finché non vengono sottoposte ad
audit, quindi i controlli riguardano i valori emessi anziché la configurazione.

- **Legga i numeri dai record creati, non dalla configurazione del campo.** La configurazione le
  dice che cosa il motore intende fare; solo un numero emesso le dice che cosa ha fatto.
- **Crei almeno tre record** e confermi l'incremento, anziché crearne uno e dare il resto per
  scontato.
- **Rilegga il contatore** dopo ogni modifica della configurazione — le componenti dell'anno e del
  conteggio devono corrispondere all'ultimo numero emesso. Rilegga contemporaneamente anche il
  *pattern*: è quella la stringa da riutilizzare per la modifica successiva.
- **Dopo ogni modifica del pattern, pubblichi, poi crei un record** e confronti il suo numero con
  il più alto già emesso. Richiede pochi secondi ed è il controllo che intercetta un contatore che
  non ha proseguito dal valore precedente.
- **Verifichi l'univocità con una query**, non come presupposto: raggruppi per il campo del numero
  e confermi che nessun valore compaia due volte. Lo faccia dopo ogni modifica della
  configurazione, e una volta come controllo pianificato se i numeri contano per l'audit.
- **Se l'azzeramento annuale è attivo, lo verifichi a un vero passaggio d'anno** prima di farvi
  affidamento. Noi non abbiamo potuto farlo, e lo diciamo anziché affermare un comportamento che
  non abbiamo visto accadere.

**Che cosa segnalerebbe una regressione:** qualsiasi valore duplicato nel campo del numero; un
contatore la cui componente dell'anno non corrisponde ai numeri emessi; un record creato con un
numero vuoto, il che significa che ha fallito un processo di composizione e non il campo nativo.

## Blueprint correlati

- [Blueprint 001 — Come gestisce cinque tipi diversi di richieste dei clienti in un unico help
  desk?](https://blueprints.coevera.com/it/blueprints/one-entity-five-request-types/) — una coda,
  cinque tipi di richiesta e un'unica serie di numeri di riferimento per tutti.
- [Blueprint 011 — Come mantiene gestibili centinaia di automazioni del
  CRM?](https://blueprints.coevera.com/it/blueprints/keeping-hundreds-of-automations-maintainable/)
  — il processo di composizione che serve quando l'anno deve provenire da una data del documento
  anziché dalla data di creazione.
- [Blueprint 008 — Come prevede rinnovi che non esistono ancora come
  record?](https://blueprints.coevera.com/it/blueprints/forecasting-renewals-before-they-exist/) —
  la stessa separazione tra ordine di creazione e data di riferimento aziendale, in una previsione
  anziché in un numero.

## Domande frequenti

### Un CRM può generare un numero di riferimento che riparte da 1 ogni anno?

Sì. In Coevera CRM un campo Auto number è costruito da un pattern di segmenti — testo letterale, un token Year e un segmento Autocount — e il segmento Autocount prevede una scelta esplicita tra azzerare il conteggio ogni anno e non azzerarlo mai. Non serve alcuna automazione. Un pattern composto da testo più Year più un conteggio a quattro cifre produce valori come TST20260001; il conteggio a quattro cifre è stato accettato tramite l'API, mentre il centro assistenza indica per il numero un minimo di cinque cifre in un pattern impostato nell'interfaccia. L'opzione di azzeramento annuale esiste; il ritorno del conteggio a 1 a un reale cambio d'anno non è stato osservato.

### Come viene memorizzato il contatore di un numero generato automaticamente?

Come uno stato in tre parti: anno, mese e numero di sequenza. In Coevera questo è esposto sul campo come last_particle. Dopo due record con un pattern che contiene un token Year ma nessun token del mese, riporta anno 2026, mese 0, numero di sequenza 2 — la componente del mese resta a zero quando il pattern non la usa. La componente dell'anno è ciò che rende possibile l'azzeramento annuale: il motore confronta l'anno memorizzato con quello corrente.

### Come si cambia il pattern di un campo a numerazione automatica esistente?

Tramite l'API, che il centro assistenza non descrive: secondo il centro assistenza le opzioni non si possono modificare dopo Save. Invii il nuovo pattern senza l'indice iniziale. Il token del conteggio può contenerne uno — scritto come una virgola e un numero all'interno del token, per esempio Number4 seguito da una virgola e da 1 — e questo indica al motore di iniziare la serie da quel valore. Viene eseguito ogni volta che viene inviato, anche su un campo che ha già emesso migliaia di numeri, quindi una modifica del pattern che mantiene l'indice iniziale fa ripartire la serie da quel numero e riemette valori già in uso. Scrivere il token del conteggio senza la virgola e il numero lascia intatto il contatore e cambia soltanto ciò che si intendeva cambiare. Inoltre l'indice iniziale viene rimosso dalla normalizzazione una volta pubblicato il campo, quindi il pattern che un campo restituisce non è il pattern con cui è stato creato: la procedura sicura è leggere il campo, prenderne il pattern alla lettera, modificare solo la parte che si intende cambiare e inviare quello. Verifichi il risultato su un numero emesso per un record appena creato, anziché sulla configurazione del campo.

### L'anno in un numero di documento può provenire da una data di fattura anziché dalla data di creazione?

Non dal campo Auto number stesso. Il suo token Year si risolve dal momento in cui il record viene creato, e il contatore avanza in ordine di creazione, quindi un numero il cui anno deve derivare da un campo data separato — una data di fattura o di documento che può differire dalla data di creazione — non può essere prodotto in modo nativo. Quel caso richiede di comporre il numero visibile in un processo di automazione a partire da un semplice contatore più l'anno del campo data scelto, e di accettare che i due possano divergere.

---

Pubblicato da Coevera. Ridotto allo schema riutilizzabile: nessun nome di cliente, nessun dato
dei clienti, nessun dato personale.