Entità Cliente
Comprendere l'oggetto Customer, il suo ciclo di vita e come si collega all'ecosistema finanziario.
Entità Cliente
Il Customer è il nodo centrale dell'ecosistema DonutWork. Rappresenta l'entità legale o l'individuo che consuma i tuoi servizi e genera fatturato.
Utilizzo
L'entità Customer viene utilizzata per:
- Tracciare le informazioni di contatto e di fatturazione.
- Associare abbonamenti ricorrenti e addebiti una tantum.
- Memorizzare metadati personalizzati tramite proprietà dinamiche per un'integrazione profonda con la tua piattaforma.
- Monitorare il rischio finanziario e la salute del business (MRR/YRR).
Flusso Operativo Atteso
Per gestire correttamente l'onboarding e la fatturazione di un cliente, segui questo flusso logico:
Inizializzazione Identità
Crea l'entità tramite l'endpoint POST /customers.json. Assegna un externalId univoco dal tuo database interno per mantenere una sincronizzazione perfetta tra i sistemi.
Arricchimento del Contesto
(Opzionale) Usa PUT /customers/{id}/properties.json per salvare dati specifici come tier di fatturazione, lingua preferita o quote API personalizzate.
Onboarding Pagamento Sicuro
Richiama GET /customers/{id}/payment_link.json. Questo genera un URL temporaneo: reindirizza l'utente a questa pagina per permettergli di inserire la carta di credito in modo sicuro e conforme PCI via Stripe.
Attivazione e Billing
Una volta che il metodo di pagamento è collegato (confermato via Webhook), attiva i servizi. Puoi associare una Subscription per ricavi ricorrenti o creare un Charge per costi una tantum.
Schema Dati
La seguente tabella definisce la struttura principale dell'oggetto Customer:
| Campo | Tipo | Descrizione |
|---|---|---|
id | eid | Identificativo univoco esteso generato da DonutWork. |
external_id | string | Il tuo identificativo di sistema interno. |
email | string | Email primaria di contatto e fatturazione. |
company_name | string | Ragione sociale utilizzata per la fatturazione. |
address | object | Dati geografici (la nazione è obbligatoria per la logica fiscale). |
properties | array | Coppie chiave-valore per dati di integrazione personalizzati. |
status | string | active, suspended, o deleted. |
Grafo delle Chiamate (Relationship)
Questo grafo illustra come l'entità Customer interagisce con gli altri componenti del sistema durante il suo ciclo di vita.