Introduzione

Questa sezione definisce gli schemi per tutti gli eventi relativi alla gestione dei clienti su Webround Commerce. Include la gestione del profilo, le richieste di sistema (reset password, verifica email) e gli indirizzi salvati.

Tabella Completa Eventi e Payload

Evento	Payload Schema	Esempio JSON
`store.customer.created`	Customer Schema	Link
`store.customer.updated`	Customer Schema	-
`store.customer.deleted`	Customer Deleted Schema	Link
`store.customer.reset-password.request`	Request Schema	Link
`store.customer.verify-email.request`	Request Schema	-
`store.customer.delete.request`	Request Schema	-
`store.customer.email.verified`	Email Verified Schema	Link
`store.customer.promotions.replaced`	Promotions Replaced Schema	Link
`store.customer.address.created`	Address Event Schema	Link
`store.customer.address.updated`	Address Event Schema	-
`store.customer.address.deleted`	Address Deleted Schema	-

Tipi di dato base

Oltre ai Tipi Base già definiti, questi eventi introducono il campo, che è inserito fuori dall'oggetto data:

Campo	Tipo	Descrizione
autonomous	`boolean`	Indica se l'azione è stata compiuta autonomamente dal cliente (`true`) o da un amministratore (`false`).

Schema Cliente (`storeCustomerCreatedSchema`)

Campo	Tipo	Note
autonomous	`boolean`	Obbligatorio (fuori dall'oggetto `data`)
id	`uuid`	Obbligatorio
storeId	`uuid`	Obbligatorio
displayName	`string - null`	Nome visualizzato
email	`string - null`	Email del cliente
address	`object - null`	Indirizzo (formato libero)
phone	`string - null`	Numero di telefono
metadata	`object - null`	Metadati custom
vatExempt	`boolean`	Obbligatorio (Esenzione IVA)
vatCode	`string - null`	Partita IVA
newsletter	`boolean`	Obbligatorio (Consenso marketing)
createdAt	`isoDate`	Obbligatorio
updatedAt	`isoDate`	Obbligatorio

Esempio Cliente

{
    "envelopeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "store.customer.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T20:30:00.000Z",
    "autonomous": true,
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
        "displayName": "John doe",
        "email": "[email protected]",
        "address": null,
        "phone": "+391234567890",
        "metadata": {
            "key": "value"
        },
        "vatExempt": false,
        "vatCode": null,
        "newsletter": true,
        "createdAt": "2026-02-22T20:30:00.000Z",
        "updatedAt": "2026-02-22T20:30:00.000Z"
    },
    "eventId": "5b7137c3-d261-40d8-aeb0-ad4831209b4b"
}

Schema Cliente Eliminato (`storeCustomerDeletedSchema`)

Campo	Tipo	Note
autonomous	`boolean`	Obbligatorio
isSoftDeletion	`boolean`	Obbligatorio (Indica se l'eliminazione è solo una procedura di anonimizzazione)
customerId	`uuid`	Obbligatorio
storeId	`uuid`	Obbligatorio

suggerimento

I clienti che hanno eseguito un ordine in passato ed erano autenticati, vengono anonimizzati ma non cancellati.

Esempio Cliente Eliminato

{
    "envelopeId": "b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7",
    "eventType": "store.customer.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T20:35:00.000Z",
    "autonomous": false,
    "isSoftDeletion": true,
    "data": {
        "customerId": "cb183be9-cd26-4061-ab27-f859a79a745e",
        "storeId": "7292a83e-967b-4861-80a5-2964e52003c4"
    },
    "eventId": "ed80464a-4d5b-4644-b55b-a8e4099e422a"
}

Schema Richiesta di Sistema (`Request Schema`)

Questo schema viene utilizzato per gli eventi di servizio che richiedono un'azione tramite URL firmato, come il reset della password, la verifica dell'email o la richiesta di cancellazione dell'account.

Campo	Tipo	Note
autonomous	`boolean`	Obbligatorio
customerId	`uuid`	Obbligatorio
email	`string`	Obbligatorio (Email del destinatario)
signedUrl	`string`	Obbligatorio (URL firmato con scadenza per completare l'azione)

Esempio Richiesta di Sistema

{
    "envelopeId": "c3d4e5f6-a1b2-4c3d-d4e5-f6g7h8i9j0k1",
    "eventType": "store.customer.reset-password.request",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T20:40:00.000Z",
    "autonomous": true,
    "data": {
        "customerId": "3eb35f07-1aa8-4e24-b221-3502d53d0837",
        "email": "[email protected]",
        "signedUrl": "https://commerce-api.webround.com/store-customers-auth/reset-password?token=abc123signed"
    },
    "eventId": "1a635d33-9233-4131-8e9b-c5b7539f152a"
}

Schema Email Verificata (`storeCustomerEmailVerifiedSchema`)

Campo	Tipo	Note
customerId	`uuid`	Obbligatorio
email	`string`	Obbligatorio

Esempio Email Verificata

{
    "envelopeId": "d4e5f6g7-h8i9-j0k1-l2m3-n4o5p6q7r8s9",
    "eventType": "store.customer.email.verified",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T20:45:00.000Z",
    "data": {
        "customerId": "9670a73e-7b85-4dc2-88b7-e475c26073bd",
        "email": "[email protected]"
    },
    "eventId": "9670a73e-7b85-4dc2-88b7-e475c26073bd"
}

Schema Promozioni Cliente (`storeCustomerPromotionsReplacedSchema`)

Campo	Tipo	Note
customerId	`uuid`	Obbligatorio
email	`string`	Obbligatorio
promotions	`object[]`	Array di oggetti contenenti `id` (uuid) e `code` (string)

Esempio Promozioni Cliente

{
    "envelopeId": "e5f6g7h8-i9j0-k1l2-m3n4-o5p6q7r8s9t0",
    "eventType": "store.customer.promotions.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T20:50:00.000Z",
    "data": {
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "email": "[email protected]",
        "promotions": [
            {
                "id": "e1c37ef6-70a5-40a8-9651-61ebcbb2d175",
                "code": "WELCOME2026"
            }
        ]
    },
    "eventId": "db44d050-532c-4634-846f-29623650647e"
}

Schema Indirizzo Cliente (`storeCustomerAddressCreatedSchema`)

Utilizzato per gli eventi di creazione e aggiornamento degli indirizzi nel profilo del cliente.

Campo	Tipo	Note
autonomous	`boolean`	Obbligatorio
customerId	`uuid`	Obbligatorio
address.id	`uuid`	Obbligatorio
address.fullName	`string - null`	Nome completo
address.company	`string - null`	Ragione sociale
address.addressLine1	`string`	Obbligatorio
address.addressLine2	`string - null`	Riga 2
address.city	`string`	Obbligatorio
address.postalCode	`string`	Obbligatorio
address.countryCode	`string`	Obbligatorio (ISO 3166-1 alpha-2)
address.phone	`string - null`	Telefono
address.province	`string - null`	Provincia
address.additionalInfo	`string - null`	Note extra
address.isDefaultShipping	`boolean`	Obbligatorio
address.isDefaultBilling	`boolean`	Obbligatorio
address.createdAt	`isoDate`	Obbligatorio
address.updatedAt	`isoDate`	Obbligatorio

Esempio Indirizzo Cliente

{
    "envelopeId": "f6g7h8i9-j0k1-l2m3-n4o5-p6q7r8s9t0u1",
    "eventType": "store.customer.address.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:00:00.000Z",
    "autonomous": true,
    "data": {
        "customerId": "88337d3d-889c-4a52-b80c-4593a2d19c5e",
        "address": {
            "id": "830b9969-46f5-4147-9d8e-cac88d10aba1",
            "fullName": "John Doe",
            "company": null,
            "addressLine1": "Corso Vittorio Emanuele II, 1",
            "addressLine2": null,
            "city": "Torino",
            "postalCode": "10121",
            "countryCode": "IT",
            "phone": "+390111234567",
            "province": "TO",
            "additionalInfo": "Secondo piano",
            "isDefaultShipping": true,
            "isDefaultBilling": true,
            "createdAt": "2026-02-22T21:00:00.000Z",
            "updatedAt": "2026-02-22T21:00:00.000Z"
        }
    },
    "eventId": "84e37079-84c5-4889-9309-f2bd35f6b25d"
}

Schema Indirizzo Eliminato (`storeCustomerAddressDeletedSchema`)

Campo	Tipo	Note
autonomous	`boolean`	Obbligatorio
customerId	`uuid`	Obbligatorio
addressId	`uuid`	Obbligatorio (ID dell'indirizzo rimosso)

Esempio Indirizzo Eliminato

{
    "envelopeId": "0a1b2c3d-4e5f-6g7h-8i9j-k0l1m2n3o4p5",
    "eventType": "store.customer.address.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:05:00.000Z",
    "autonomous": true,
    "data": {
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "addressId": "0164a96e-62cf-42e6-9fbd-16308f4d7e85"
    },
    "eventId": "84e37079-84c5-4889-9309-f2bd35f6b25d"
}

Tabella Completa Eventi e Payload

Tipi di dato base​

Schema Cliente (storeCustomerCreatedSchema)​

Esempio Cliente​

Schema Cliente Eliminato (storeCustomerDeletedSchema)​

Esempio Cliente Eliminato​

Schema Richiesta di Sistema (Request Schema)​

Esempio Richiesta di Sistema​

Schema Email Verificata (storeCustomerEmailVerifiedSchema)​

Esempio Email Verificata​

Schema Promozioni Cliente (storeCustomerPromotionsReplacedSchema)​

Esempio Promozioni Cliente​

Schema Indirizzo Cliente (storeCustomerAddressCreatedSchema)​

Esempio Indirizzo Cliente​

Schema Indirizzo Eliminato (storeCustomerAddressDeletedSchema)​

Esempio Indirizzo Eliminato​