Gestisci il negozio via API

Autenticazione e permessi

Authorization: Bearer <token>

• di un utente staff: si ottiene con POST /auth/login e si rinnova con il refresh a rotazione (vedi Autenticazione). Per gli account staff un refresh token superato e riusato chiude la sessione: non condividerlo fra processi.
• un token API: la credenziale consigliata per integrazioni e agenti che lavorano a lungo. Si usa come Bearer, senza login né refresh, ha un ruolo scelto e una scadenza obbligatoria (da 1 a 365 giorni) e si revoca all’istante. Lo genera un amministratore, se la funzione è abilitata per il negozio (GET /admin/api-tokens/status; altrimenti 403 tenant_keys.admin_api_disabled).

curl -X POST "$BASE/api/v1/admin/api-tokens" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" \
  -d '{"label":"Sync ERP","role":"catalog_manager","expires_in_days":90}'
# data.token è mostrato una sola volta: conservalo come un segreto.
# Revoca: POST /admin/api-tokens/{id}/revoke

Regole che contano per chi integra

Soldi: chi può fare cosa

Titolare, utenti staff e token API

• Ogni negozio ha un titolare: un amministratore attivo, registrato e stabile, che non cambia se si promuove un altro account. GET /auth/me e la lista utenti lo indicano con is_owner: true. Lo cambia solo l’assistenza Vellaro.
• Il titolare è protetto: password, ruolo, disattivazione, eliminazione e reset della 2FA del suo account rispondono 403 user.owner_protected. Sugli altri amministratori le stesse azioni le fa solo il titolare (403 user.owner_only). Un’azione che lascerebbe il negozio senza amministratori attivi dà 409 user.last_admin.
• Un token API non gestisce utenti né credenziali: creare, modificare o eliminare utenti staff, resettarne la 2FA, generare o revocare token API e chiavi publishable risponde 403 auth.api_token_forbidden. Le letture restano permesse.

Ordini, rimborsi e resi

• Le transizioni di stato sono validate: una non ammessa dà 409 order.invalid_transition.
• comment è una nota interna per impostazione predefinita; con comment_public: true la vede anche il cliente nella sua cronologia.
• Un rimborso totale o l’annullo di un ordine pagato restituiscono anche la parte pagata con un buono regalo. Lo stock rientra una volta sola.
• I resi partono da una riga dell’ordine: GET /admin/returns/order-context/{order_id} elenca le righe con le quantità restituibili, poi POST /admin/returns. Una variante fuori dall’ordine o una quantità oltre il restituibile danno 422 return.item_not_in_order / return.quantity_exceeds_order. Motivi e stati dei resi sono un catalogo comune in sola lettura (403 return.lookup_global sulle scritture).

curl -X POST "$BASE/api/v1/admin/orders/<id>/refunds" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" \
  -d '{"amount":"20.00","reason":"Articolo danneggiato","restock":true,"notify_customer":true}'
# → { "data": { "transaction": {...}, "payment_status": "partially_refunded",
#               "amount_refunded": "20.00", "restocked": false } }

Catalogo e prezzi

curl -X POST "$BASE/api/v1/admin/products" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{
    "name": "Divano Como 3 posti",
    "slug": "divano-como-3-posti",
    "category_id": "<uuid categoria>",
    "is_active": true,
    "variants": [
      { "sku": "COMO-3P-GRIGIO", "name": "Grigio", "price": "1299.00", "stock": 5 },
      { "sku": "COMO-3P-BLU", "name": "Blu", "price": "1299.00", "stock": 2 }
    ]
  }'

• Prezzi speciali e sconti a quantità (/admin/products/{id}/specials, /discounts): il price deve essere maggiore di zero, altrimenti 422 product.price_rule_not_positive. Uno speciale vale per tutti (customer_group_id: null) o per un gruppo clienti attivo, nella sua finestra di date; fra più speciali vince la priority più bassa, poi il prezzo più basso. Lo speciale può solo abbassare il prezzo, e carrello e checkout lo applicano.
• Saldo sulla variante: sale_price, sale_start e sale_end vanno insieme (422 product.sale_window_invalid se la finestra non è valida); per toglierlo mandali tutti e tre a null.

Coupon e buoni regalo

• I coupon sono validati in creazione e modifica: 422 coupon.percentage_out_of_range, coupon.negative_discount, coupon.dates_inverted; 409 coupon.code_taken. La lista ha il filtro status (active, scheduled, expired, exhausted, inactive).
• DELETE /admin/coupons/{id} elimina davvero un coupon mai usato (il codice torna libero) e disattiva quello già usato: leggi deleted e deactivated nella risposta.
• Buoni regalo (/admin/vouchers, permesso marketing): codice, importo e saldo. Il saldo si spende al checkout (voucher_code), con amount_spent, redemption_count e lo storico in GET /admin/vouchers/{id}/history. Anche qui DELETE elimina solo un buono mai speso e altrimenti lo disattiva.

Abbonamenti e piani ricorrenti

{
  "name_i18n": { "it": "Ricarica mensile", "en": "Monthly top-up" },
  "price": "9.90", "frequency": "month", "duration": 1, "cycle": 12,
  "trial_status": true, "trial_frequency": "day", "trial_duration": 14,
  "is_active": true
}

Clienti e affiliati

curl -X POST "$BASE/api/v1/admin/customers/<id>/anonymize" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{"confirm_email":"cliente@example.com"}'

• Disattivare un cliente (PATCH /admin/customers/{id} con is_active: false) chiude subito tutte le sue sessioni.
• Commissioni degli affiliati (/admin/affiliate-commissions): si leggono con customers; approvare, segnare pagata o rifiutare richiede anche reports. Il riepilogo (/summary) ha una riga per affiliato e valuta: le valute non si sommano mai.

Report

• Un ordine conta come ricavo se è incassato (paid o partially_refunded, non refunded); l’importo è il netto, totale meno rimborsato.
• I numeri principali sono nella valuta base del negozio (campo currency); gli incassi in altre valute stanno a parte in other_currencies.
• «Oggi», giorni e mesi seguono il fuso del negozio, restituito in timezone.

Impostazioni del negozio

curl -X PUT "$BASE/api/v1/admin/settings" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{
    "group": "orders", "store_id": null,
    "settings": [
      { "key": "guest_checkout_allowed", "value": "false" },
      { "key": "min_order_total", "value": "20.00" }
    ]
  }'

Esempi

# lista prodotti (include gli inattivi, per la gestione)
curl "$BASE/api/v1/admin/products?page=1&page_size=24" -H "Authorization: Bearer $STAFF"

# ordini + cambio stato (con transizioni validate)
curl "$BASE/api/v1/admin/orders?status=pending" -H "Authorization: Bearer $STAFF"
curl -X PATCH "$BASE/api/v1/admin/orders/<id>" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "status":"processing" }'

Buone pratiche

• Errori: fai switch su error_code. Un 403 plan.required significa che la funzione non è inclusa nel piano del negozio: non ritentare.
• Idempotenza & bulk: per aggiornamenti massivi (prezzi, stock), procedi a batch e gestisci i 409/422 per riga.
• Audit: ogni mutazione admin è registrata nell’audit log del negozio.
• Soft-delete: eliminare un prodotto imposta deleted_at (non distrugge lo storico ordini); disattivare è cosa diversa (is_active).
• Webhook: per reagire agli eventi senza polling usa i webhook.
• Versioning: l’API è su /api/v1 — cambi retrocompatibili; le rotture andranno su una nuova versione.