Custom Engine (Mapper YAML)

Il Custom Engine permette di integrare tenant con API proprietarie non conformi a salesmate_api.yaml, senza cambiare i Service Module.

Esempio tenant YAML

tenant_id: tenantexample
tenant_type: custom
api_base_url: https://tenant.example.com
store_base_url: https://tenant.example.com
ext_base_url: https://tenant.example.com

auth:
  type: basic
  username: <username>
  password: <password>

custom_engine: true

endpoints:
  GET /products: /api/v2/articoli
  GET /products/{id}: /api/v2/articoli/{id}
  GET /products/{id}/variations: /api/v2/articoli/{id}/varianti
  GET /products/categories: /api/v2/categorie
  GET /orders: /api/v2/ordini
  GET /orders/{id}: /api/v2/ordini/{id}
  GET /customers/{id}: /api/v2/clienti/{id}
  PUT /customers/{id}: /api/v2/clienti/{id}
  POST /cart/session: /api/v2/carrello/sessione
  GET /cart: /api/v2/carrello
  POST /cart/add-item: /api/v2/carrello/aggiungi
  DELETE /cart/remove-item: /api/v2/carrello/rimuovi
  POST /checkout: /api/v2/ordina

params:
  per_page: limit
  page: offset
  customer: customer_id

mapping:
  product:
    id: generated:sorting+code
    name: description
    sku: code
    type: static:simple
    price: prices|format_decimal
    regular_price: prices|format_decimal
    sale_price: "static:"
    stock_quantity: quantity
    stock_status: quantity|instock_if_gt_zero
    description: description_long.ITA.value|fallback:description
    short_description: description_long.ITA.value|strip_html|truncate:300
    images.src: source_image_path
    images.alt: description
    categories.id: generated:category_id
    categories.name: category.description.ITA.value
    categories.slug: category.code|lowercase

  product_variation:
    id: id
    sku: sku
    price: price|format_decimal
    regular_price: regular_price|format_decimal
    sale_price: sale_price|format_decimal
    stock_status: stock_status
    stock_quantity: stock_quantity
    attributes: attributes

  category:
    id: generated:sorting
    name: description.ITA.value
    slug: code|lowercase
    parent: static:0
    count: computed:products_per_category

  order:
    id: id
    status: stato|map:{"in_attesa":"pending","completato":"completed","annullato":"cancelled"}
    total: totale|format_decimal
    currency: static:EUR
    date_created: data_creazione
    line_items: prodotti

  customer:
    id: id_cliente
    email: email
    first_name: nome
    last_name: cognome
    billing: indirizzo_fatturazione
    shipping: indirizzo_spedizione

  cart_session:
    cart_token: cart_token
    expires_at: expires_at
    customer_id: customer_id

  cart:
    items: items
    totals: totals

  checkout:
    order_id: order_id
    status: status
    order_key: order_key
    total: total
    currency: currency
    customer_note: customer_note

Note endpoints

- La chiave è sempre "METHOD /path-salesmate"
- Supporta placeholder con {id} (es. GET /products/{id})
- Se un endpoint non è presente in mappa, viene usato il path originale (tenant parzialmente mappati)

Note params

- Rinomina parametri query (es. per_page → limit)
- Caso speciale page → offset: se params contiene "page: offset", viene calcolato offset=(page-1)*per_page

Trasformazioni disponibili

lowercase
strip_html
truncate:N
format_decimal
instock_if_gt_zero
fallback:campo_alt
map:{...}

Se una regola non trova il campo sorgente, il server logga un WARNING e ritorna un default (senza eccezioni).