Entità Addebito (Charge)

Un Charge (chiamato anche Transazione) rappresenta un saldo finanziario specifico associato a un Customer. Può essere generato automaticamente dal rinnovo di un abbonamento o creato manualmente per servizi una tantum.

Utilizzo

L'entità Charge viene utilizzata per:

Processare pagamenti ad-hoc per costi di setup, consulenza o hardware.
Archiviare lo storico degli eventi di fatturazione ricorrente.
Gestire l'associazione con documenti legali (fatture e ricevute).
Tracciare in tempo reale lo stato del pagamento (Pending, Paid, Refunded).

Pagamenti importati da un altro sistema

Un pagamento già incassato esternamente si registra tramite POST /customers/{customerId}/charges/import.json con charges:write. Il risultato è una charge one-shot pagata, con instruction=external ed externally_managed=true. Imponibili, imposte e date originali vengono conservati. Non vengono effettuati incassi sul gateway, non serve un metodo di pagamento sul cliente e non si creano o rinnovano abbonamenti.

Commissioni partner ed eventuali referral seguono le regole esistenti; l'importazione emette Charge.create e Charge.succeeded. Il record economico non è modificabile o rimborsabile attraverso i normali percorsi di pagamento e cambio stato di Donutwork; i metadati fattura restano aggiornabili separatamente. Il backoffice mostra un badge di importazione accanto alla descrizione, con il sistema sorgente nel tooltip. Consulta importare charge esterne per payload, chiave della transazione sorgente e gestione dei retry.

Flusso Atteso

Ciclo di vita di una transazione finanziaria manuale:

Generazione: Crea l'oggetto charge con una o più righe di servizio.
Esecuzione: Se il capture è abilitato, il sistema utilizza il metodo di pagamento predefinito del cliente.
Adempimento: Dopo il successo, i dettagli formali della fattura vengono allegati per la sincronizzazione contabile.

Schema Dati

I campi che definiscono un oggetto Charge:

Campo	Tipo	Descrizione
`id`	`string`	Identificativo univoco esadecimale della charge, di 24 caratteri.
`customer_id`	`string`	Il proprietario della transazione.
`total`	`number`	Totale lordo della transazione, imposte incluse.
`type`	`string`	Categoria della charge; i pagamenti importati usano `one-shot`.
`instruction`	`string`	Istruzione di pagamento; `external` identifica un pagamento importato.
`externally_managed`	`boolean`	True per le charge importate il cui pagamento è gestito dal sistema sorgente.
`paid_at`	`string` oppure `null`	Data di pagamento ISO 8601; l'importazione conserva la data di incasso esterna.
`metadata.paid`	`object`	Metadati di pagamento nel dettaglio; le importazioni includono `external_source`, `external_id` e `currency`.
`status`	`string`	Stato corrente: `pending`, `paid`, `refunded`, `failed`.
`services`	`array`	Elenco degli articoli addebitati con relativi profili fiscali.
`invoice`	`object`	Metadati contabili (numero, data, link esterno), letti e aggiornati tramite l'endpoint fattura dedicato.
`date`	`string` oppure `object`	Nelle liste è la data originale di creazione ISO 8601; nel dettaglio è un oggetto data dell'ultimo aggiornamento.

Grafo delle Chiamate (Relationship)

Come i Charge interagiscono con i gateway di pagamento esterni: