SS
AppTeam eStore Platform Documentazione pubblica
Landing Indice documenti
Integrazioni

API, Flussi e Integrazioni

Licenze, attivazioni, aggiornamenti e collegamenti tra control center, client e servizi esterni.

Torna all'indice Vai alla landing

1. Obiettivo di questo documento

Questo documento descrive il layer di integrazione della piattaforma:

  • API esposte dal backend
  • flussi applicativi principali
  • relazioni tra app, backend, Shopify e OneSignal

E' pensato per essere leggibile sia da un team tecnico sia da un cliente avanzato che voglia comprendere come la piattaforma opera realmente.

2. Endpoint API pubblici dell'app

2.1 Stato piattaforma

GET /api/v1/platform/status

Scopo:

  • capire se la piattaforma e' installata
  • fornire dati base dell'istanza
  • esporre la disponibilita' della configurazione push

3. Catalogo

3.1 Home

GET /api/v1/catalog/home

Restituisce una risposta aggregata che include:

  • branding pubblico
  • slide attive
  • categorie visibili
  • prodotti in evidenza o recenti
  • link legali e contatti

3.2 Collections

GET /api/v1/catalog/collections

Restituisce:

  • collezioni visibili in app
  • numero prodotti
  • immagine collegata
  • eventuale immagine custom locale

3.3 Dettaglio collection

GET /api/v1/catalog/collections/{collection}

Restituisce:

  • dettaglio collection
  • prodotti associati tramite mapping locale

3.4 Lista prodotti

GET /api/v1/catalog/products

Supporta:

  • query di ricerca
  • limit

3.5 Dettaglio prodotto

GET /api/v1/catalog/products/{product}

Restituisce:

  • dati base prodotto
  • media
  • varianti
  • prezzo e range prezzo
  • informazioni utili al dettaglio app

4. Commerce

4.1 Checkout

POST /api/v1/commerce/checkout

Payload logico:

{
  "lines": [
    {
      "variant_id": 123,
      "quantity": 2
    }
  ]
}

Funzioni del backend:

  • valida il payload
  • verifica l'esistenza delle varianti nel DB locale
  • filtra prodotti attivi
  • crea un cart Shopify
  • allega buyer identity se esiste una sessione cliente

Risposta logica:

{
  "data": {
    "checkout_url": "https://shopify-domain/cart/..."
  }
}

5. Customer account

5.1 Login cliente

POST /api/v1/customer/login

Payload logico:

{
  "email": "cliente@example.com",
  "password": "password",
  "device_subscription_id": "optional-device-id"
}

Effetti:

  • login su Shopify Storefront API
  • creazione sessione locale backend
  • eventuale allineamento push identity

5.2 Registrazione cliente

POST /api/v1/customer/register

Crea il cliente su Shopify e genera la sessione locale applicativa.

5.3 Recupero password

POST /api/v1/customer/password/recover

Delegato alla meccanica di recovery prevista da Shopify.

5.4 Logout

POST /api/v1/customer/logout

Disponibile solo con middleware customer.auth.

Effetti:

  • revoca sessione locale
  • pulizia allineamento identita' push

5.5 Profilo

GET /api/v1/customer/me

Restituisce:

  • anagrafica cliente
  • dati utili alla tab profilo

5.6 Ordini

GET /api/v1/customer/orders

Restituisce:

  • lista ordini del cliente autenticato
  • totale
  • stato
  • righe principali
  • link allo status order

6. Push devices

6.1 Registrazione device

POST /api/v1/push/devices

Payload logico:

{
  "subscription_id": "sub-001",
  "onesignal_id": "one-user-001",
  "push_token": "token",
  "platform": "android",
  "notification_email": "cliente@example.com",
  "notifications_enabled": true
}

Scopo:

  • creare o aggiornare il registro dispositivi
  • associare il device a una email
  • permettere notifiche ordine e promozionali mirate

7. Webhook Shopify

7.1 Endpoint unico

POST /api/v1/shopify/webhooks

La piattaforma usa un endpoint unico per tutti i topic supportati. Il controller distingue il comportamento in base all'header X-Shopify-Topic.

7.2 Topic gestiti

Esempi di topic supportati:

  • products/create
  • products/update
  • products/delete
  • collections/create
  • collections/update
  • collections/delete
  • orders/create
  • orders/paid
  • orders/cancelled

7.3 Flusso interno

  1. valida HMAC
  2. identifica lo shop
  3. registra webhook_events
  4. processa l'evento
  5. aggiorna lo stato di processamento

8. Flusso end-to-end: installazione

sequenceDiagram
    participant U as Utente Installazione
    participant W as Wizard Laravel
    participant DB as Database
    participant S as Shopify

    U->>W: Compila step database
    W->>DB: Salva configurazione e verifica connessione
    U->>W: Crea admin
    W->>DB: Crea user e shop
    U->>W: Inserisce credenziali Shopify
    W->>S: Test connessione e token exchange
    U->>W: Avvia import
    W->>S: Scarica catalogo
    W->>DB: Salva prodotti, varianti, collection
    U->>W: Registra webhook
    W->>S: Crea subscription webhook
    U->>W: Salva branding
    W->>DB: Salva app settings

9. Flusso end-to-end: login cliente

sequenceDiagram
    participant A as App Flutter
    participant B as Backend Laravel
    participant S as Shopify Storefront
    participant O as OneSignal

    A->>B: POST /customer/login
    B->>S: customerAccessTokenCreate
    S-->>B: customerAccessToken
    B->>S: query customer
    B->>B: Crea customer session locale
    B->>O: Allinea identita' push se device presente
    B-->>A: token sessione + profilo

10. Flusso end-to-end: ordini cliente

sequenceDiagram
    participant A as App Flutter
    participant B as Backend Laravel
    participant S as Shopify Storefront

    A->>B: GET /customer/orders
    B->>B: Valida customer session
    B->>S: query customer.orders
    S-->>B: lista ordini
    B-->>A: ordini normalizzati

11. Flusso end-to-end: checkout

sequenceDiagram
    participant A as App Flutter
    participant B as Backend Laravel
    participant S as Shopify Storefront

    A->>B: POST /commerce/checkout
    B->>B: Valida righe e varianti locali
    B->>S: cartCreate
    S-->>B: checkoutUrl
    B-->>A: checkoutUrl
    A->>S: Apre checkout esterno

12. Flusso end-to-end: push ordine

sequenceDiagram
    participant S as Shopify
    participant B as Backend Laravel
    participant DB as Database
    participant O as OneSignal
    participant A as App Flutter

    S->>B: webhook orders/paid
    B->>B: Valida HMAC
    B->>DB: Registra webhook event
    B->>DB: Cerca push devices per email ordine
    B->>O: Invia push
    O-->>A: Notifica al cliente

13. Strategia di sincronizzazione

La piattaforma usa un modello ibrido:

  • import iniziale completo
  • sync delta tramite webhook
  • sync manuale dal backoffice

13.1 Perche' e' efficace

Questa architettura riduce:

  • dipendenza dal live runtime Shopify per ogni schermata
  • latenze lato app
  • rischio di incoerenza prolungata

pur mantenendo:

  • aggiornamento rapido del catalogo
  • audit degli eventi
  • controllo locale della presentazione

14. OneSignal: logica di integrazione

Il payload push puo' includere:

  • titolo
  • messaggio
  • immagine
  • prodotto opzionale

Quando un prodotto e' associato, il backend invia metadati sia in:

  • data
  • custom_data

Questa doppia scrittura aumenta la compatibilita' col parsing lato mobile.

15. Contratti funzionali importanti

15.1 Shopify e' la fonte primaria

Prodotti, varianti, ordini e customer core appartengono a Shopify.

15.2 Laravel e' la fonte primaria editoriale

Branding, slide, visibilita' collection, immagini categorie e logiche push appartengono al backend Laravel.

15.3 L'app mobile non usa Shopify diretto

L'app parla con Laravel. Questo consente:

  • controllo centralizzato
  • sicurezza maggiore
  • customizzazione commerciale
  • indipendenza operativa

16. Punti di attenzione per integrazioni future

  • introdurre API versioning piu' esplicito in caso di evoluzione forte
  • pubblicare esempi OpenAPI se il progetto verra' esposto a terze parti
  • aggiungere webhook replay o retry avanzato in interfaccia
  • estendere il layer account se servono funzionalita' clienti piu' avanzate