Ordine
L'entità Ordine è il cuore della contabilità del tuo store e della cronologia degli acquisti dei clienti. Rappresenta la formalizzazione di una transazione commerciale, registrando i dettagli finanziari, logistici e personali coinvolti nell'esatto momento della vendita.
Ogni ordine è indissolubilmente legato a un Cliente (che deve essere registrato nel sistema prima della creazione dell'ordine) e contiene i dati fondamentali per la fatturazione e la consegna.
Anatomia di un Ordine
Un ordine in Webround Commerce aggrega diverse informazioni critiche:
- Dati Finanziari: Il totale complessivo (
amount), i costi di spedizione e la valuta utilizzata. - Logistica: Indirizzi di spedizione e fatturazione, stato della spedizione e l'URL di tracking per il cliente.
- Stato del Pagamento: Monitoraggio del ciclo di vita della transazione (
created,paid,failed,refunded, ecc.). - Integrazione Stripe: Campi dedicati per mappare gli ID delle sessioni di checkout di Stripe, i payment intent, gli abbonamenti e le fatture generate.
- Gestione Post-Vendita: Tracciamento di rimborsi e controversie.
Definizione
| Proprietà | Tipo | Descrizione |
|---|---|---|
| id | string (UUID) | Identificativo univoco dell'ordine. |
| storeId | string (UUID) | ID dello store in cui è stato effettuato l'acquisto. |
| customerId | string (UUID) | ID del cliente che ha effettuato l'ordine. |
| amount | string (Decimal) | Totale complessivo dell'ordine (lordo). |
| currencyCode | string | Codice valuta ISO (es. EUR). |
| paymentStatus | string | Stato del ciclo di vita del pagamento (es. paid, pending, failed). |
| shippingStatus | string | Stato della spedizione (es. unassigned, shipped, delivered). |
| stripeInvoiceUrl | string (URL) | Link diretto alla fattura generata da Stripe. |
| shippingTrackingUrl | string | null |
| items | OrderItem[] | Righe d'ordine incluse nell'ordine. |
| createdAt | string (ISO 8601) | Timestamp di creazione dell'ordine. |
| updatedAt | string (ISO 8601) | Timestamp dell'ultimo aggiornamento. |
Righe d'Ordine (Order Items)
Un ordine è più di un semplice totale finanziario: contiene i dettagli degli articoli acquistati tramite gli Order Items. Ogni riga d'ordine specifica l'esatta Variante acquistata, la quantità e l'istantanea dei prezzi "congelata" al momento della vendita.
Definizione
| Proprietà | Tipo | Descrizione |
|---|---|---|
| productId | string (UUID) | ID del prodotto padre. |
| variantId | string (UUID) | ID della specifica Variante acquistata. |
| variantName | string | Nome visualizzato della variante al momento della vendita (es. "Berretto Nero"). |
| coverUrl | string (URL) | URL dell'immagine di copertina del prodotto al momento della vendita. |
| quantity | number | Quantità acquistata per questa riga. |
| deliveryMethod | DeliveryMethod | Metodo di consegna scelto per questo articolo. |
| appliedTaxRate | number | Aliquota IVA applicata (es. 22). |
| unitNet | string (Decimal) | Prezzo unitario netto (tasse escluse). |
| unitGross | string (Decimal) | Prezzo unitario lordo (tasse incluse). |
| totalNet | string (Decimal) | Totale di riga netto (unitNet × quantità). |
| totalGross | string (Decimal) | Totale di riga lordo (unitGross × quantità). |
I valori finanziari (amount, unitNet, ecc.) vengono restituiti come string per preservare la precisione decimale durante le operazioni finanziarie, evitando gli errori di arrotondamento in virgola mobile tipici del tipo number di JavaScript.
Modalità di Gestione
Webround Commerce offre due approcci distinti alla gestione degli ordini, adattandosi sia a workflow completamente automatizzati che a necessità manuali o personalizzate.
1. Modalità Automatica (Gestita da Stripe)
In questa modalità, Webround funge da ponte intelligente verso Stripe. Il sistema crea l'ordine nel momento in cui un utente avvia una sessione di checkout.
- Workflow: Webround riceve eventi in tempo reale da Stripe tramite webhook e aggiorna l'ordine di conseguenza — inclusi pagamenti andati a buon fine, blocchi anti-frode e fallimenti.
- Integrità dei Dati: Poiché la transazione è certificata da Stripe, i totali, le quantità e gli Order Items non possono essere modificati manualmente. Questi dati sono bloccati per riflettere l'effettivo movimento di denaro.
- Cosa puoi gestire: Hai il pieno controllo sul lato logistico — nello specifico l'aggiornamento dello Stato della Spedizione e l'inserimento dell'URL di Tracciamento.
2. Modalità Manuale (Flessibilità Totale)
Questa modalità trasforma Webround in un potente strumento gestionale libero dai vincoli dell'automazione. È l'ideale per tracciare vendite effettuate nel tuo negozio fisico, ordini telefonici o importazioni massive via API da sistemi esterni.
- Autonomia: Stripe non interviene. Puoi definire prezzi, articoli e stati come preferisci.
- Modificabilità: Non ci sono blocchi sulle modifiche. Puoi aggiornare qualsiasi campo dell'ordine in qualsiasi momento per riflettere operazioni manuali o correzioni offline.
In modalità automatica, la creazione di un ordine non coincide necessariamente con un pagamento andato a buon fine. L'ordine nasce quando l'utente mostra l'intenzione di acquistare (aprendo la sessione di checkout). Questo ti permette di monitorare i checkout iniziati e analizzare potenziali colli di bottiglia nel processo di conversione.