Gestione e modello dati Ordini Web

Modello dati Ordine MagicStore

L'integrazione offre la possibilità di inviare ordini dal canale esterno al sistema MagicStore tramite chiamata REST.

La chiamata deve essere effettuata tramite il metodo POST all'URL composto da: BASE_PATH/api/order.

Per l'ambiente Sandbox: https://app-test.magicstore.cloud/api/order 

Per l'ambiente di produzione: sarà fornito dopo la fase di test.

Il body della chiamata REST è un oggetto formattato come descritto di seguito.

 

• Order

Rappresenta un ordine completo, contenente tutte le informazioni necessarie per gestire un ordine nel sistema.

Proprietà:

• String webOrderId: ID dell'ordine sul CMS.
• String orderNumber: Numero dell'ordine sul CMS (può coincidere con l'ID).
• String currencyCode: Codice della valuta secondo lo standard ISO 4217 (es., USD, EUR).
• LocalDateTime createDate: Data di creazione dell'ordine sul CMS.
• boolean taxIncluded: Indica se i prezzi sono inclusivi di tasse (true) o no (false).
• ShippingAddress shippingAddress: Indirizzo di spedizione del cliente.
• ShippingAddress billingAddress: Indirizzo di fatturazione del cliente.
• Customer customer: Oggetto contenente l'indirizzo di spedizione del cliente.
• List<OrderEntry> entries: Elenco dei prodotti nell'ordine.
• List<Payment> payments: Elenco dei pagamenti effettuati per l'ordine.
• List<Adjustment> adjustments: Elenco degli aggiustamenti (sconti, costi aggiuntivi) applicati all'ordine.
• String trackingNumber: Numero di tracciamento della spedizione.
• String carrierCode: Codice del corriere.
• String carrierName: Nome del corriere.
• String carrierService: Servizio utilizzato dal corriere.
• String externalCustomerId: ID del cliente nel CMS.
• StatusEnum operatingStatus: Stato operativo dell'ordine (OPTIONED, CONFIRMED).
• StatusEnum shippingStatus: Stato della spedizione dell'ordine (PENDING, IN_TRANSIT, DELIVERED).
• StatusEnum paymentStatus: Stato del pagamento dell'ordine (PAID, UNPAID).

 

• Customer

Rappresenta il cliente che ha effettuato l'ordine.

Proprietà:

ShippingAddress address: Indirizzo di spedizione del cliente.

 

• ShippingAddress

Rappresenta un indirizzo di spedizione o di fatturazione.

Proprietà:

• String country: Codice del paese secondo lo standard ISO 3166-1 Alpha-2 (es., IT, CH).
• String state: Stato o provincia (es., Campania).
• String city: Città (es., Napoli).
• String street: Nome della via.
• String civicNumber: Numero civico.
• String description: Nome completo del cliente (es., Antonio Attanasio).
• String postalCode: Codice postale.
• boolean encrypted: Indica se l'indirizzo è criptato (true) o no (false).

 

• OrderEntry

Rappresenta una riga dell'ordine.

Proprietà:

 

• Long productVariantId: ID della variante del prodotto.
• Integer quantity: Quantità del prodotto venduta.
• String sku: SKU del prodotto (colonna Variant_SKU nel file dei dati del prodotto).
• String additionalIdentifier: Utilizzato solo per prodotti non inviati da MagicStore, che erano già presenti nel CMS/Marketplace.
• String barcode: Codice a barre del prodotto (EAN).
• Price price: Prezzo del prodotto.
• String productDescription: Descrizione del prodotto, utilizzata solo per prodotti non inviati da MagicStore.

 

• Price

Rappresenta il prezzo di un prodotto.

Proprietà:

• BigDecimal amount: Prezzo finale del singolo prodotto.
• BigDecimal taxPercentage: Percentuale di tasse applicata.
• Long taxId: ID delle tasse applicate.
• String taxName: Nome delle tasse applicate.
• List<Adjustment> adjustments: Elenco degli aggiustamenti (sconti, spese aggiuntive) applicati al prezzo.

• Adjustment

Rappresenta un aggiustamento del prezzo (sconto, costo aggiuntivo).

Proprietà:

 

• BigDecimal percentageValue: Valore percentuale dell'aggiustamento.
• BigDecimal fixedValue: Valore fisso dell'aggiustamento.
• BigDecimal taxPercentage: Percentuale di tasse applicata sull'aggiustamento.
• AdjustmentTypeEnum type: Tipo di aggiustamento (GENERIC_DISCOUNT, ANCILLARY_CHARGE, SHIPPING_FEES).
• Long taxId: ID delle tasse applicate sull'aggiustamento. 
• String taxName: Nome delle tasse applicate sull'aggiustamento.

• Payment

Rappresenta un pagamento effettuato per l'ordine.

Proprietà:

 

• String currencyCode: Codice della valuta secondo lo standard ISO 4217 (es., USD, EUR).
• BigDecimal amount: Importo del pagamento.
• String note: Note relative al pagamento.
• LocalDateTime paymentDate: Data del pagamento.
• PaymentMethodEnum paymentMethod: Metodo di pagamento utilizzato (es., CREDIT_CARD).

 

• Enumerazioni

Enumerazioni utilizzate nel codice per rappresentare vari stati e tipologie.

 

OperationgStatusEnum

Rappresenta i diversi stati di un ordine:

 

OPTIONED: L'ordine è opzionato.

CONFIRMED: L'ordine è confermato.

ShippingStatusEnum

Rappresenta i diversi stati di spedizione di un ordine:

 

PENDING: La spedizione è in attesa.

IN_TRANSIT: La spedizione è in transito.

DELIVERED: La spedizione è consegnata.

PaymentStatusEnum

Rappresenta i diversi stati di pagamento di un ordine:

 

PAID: Il pagamento è stato effettuato.

UNPAID: Il pagamento non è stato effettuato.

 

AdjustmentTypeEnum

Rappresenta i diversi tipi di aggiustamenti di prezzo:

 

GENERIC_DISCOUNT: Sconto generico.

ANCILLARY_CHARGE: Costo aggiuntivo.

SHIPPING_FEES: Spese di spedizione.

 

PaymentMethodEnum

Rappresenta i diversi metodi di pagamento:

 

CREDIT_CARD: Pagamento con carta di credito.

 

• Status Update

Per ciascun aggiornamento dello stato relativo allo stato dell'ordine, lo stato di spedizione o lo stato del pagamento, è possibile inviare lo stesso ordine all'URL indicato in precedenza.

Il sistema riconoscerà il movimento come già inserito in MagicStore e procederà ad aggiornare solo il relativo stato. In generale, gli ordini sono caratterizzati da tre tipologie di stato: uno stato operativo, uno stato di spedizione e uno stato di pagamento.

I valori ammessi per ciascuno sono i seguenti:

 

Stato operativo:

 

OPTIONED: questo valore significa che solo la disponibilità è dedotta.

CONFIRMED: questo valore significa che la disponibilità e lo stock sono dedotti.

 

Stato di spedizione:

 

PENDING

IN_TRANSIT

DELIVERED

 

Stato di pagamento:

UNPAID

PAID