La 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.
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.
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.
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.
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.
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.
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: «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.
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.
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.
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.