Salta al contenuto principale
In questa pagina▾

Un negozio o ERP personalizzato è uno per cui non esiste un plug-in già pronto, quindi il tuo sviluppatore collega il configuratore al carrello. La regola alla base di tutto qui è una sola frase: un prezzo inviato dal browser non deve mai diventare un prezzo di carrello. Il tuo server lo verifica prima con CutOptim.

CutOptim non incassa pagamenti e non ospita negozi; carrello, checkout e pagamento restano tuoi. Non esiste ancora un SDK. Il riferimento API del configuratore elenca ogni route, codice di errore e limite, con un documento OpenAPI 3.1; questa pagina, la pagina sugli ordini e il codice di riferimento guidano l’integrazione passo per passo.

Due chiavi

  • La chiave pubblicabile sta nella tua pagina per l’integrazione. Può fare solo ciò che fa un acquirente, e solo dai domini che hai elencato per essa.
  • La chiave segreta è per il tuo server e non va mai messa in una pagina. Viene inviata come Authorization: Bearer <key> al servizio, per impostazione predefinita https://cfg.cutoptim.com. Invia sempre Content-Type: application/json in una POST.

Passo 1: verifica il preventivo prima del carrello

Quando il cliente ordina, la tua pagina riceve un evento cutoptim:order con un token di preventivo. Invia il token al tuo server e da lì:

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CFG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<token from the page>"}'

La risposta è 200 con {"valid": true, "redeemed": false, "claims": {...}} oppure {"valid": false, "reason": "..."}. Un rifiuto è comunque un 200, quindi leggi valid. Considera un timeout, un 401, un 500 o un corpo illeggibile come non verificato e rifiuta la riga. Poi confronta le claim con la tua riga di carrello: il tenant è il tuo, la valuta è quella del carrello, la scadenza è nel futuro e l’hash del preventivo è uguale all’hash del preventivo mostrato dalla tua pagina. Il codice di riferimento include la funzione che calcola quell’hash.

Un controllo locale della forma, del tenant e della scadenza del token costa meno ma non può provare la firma, perché la chiave di firma non viene distribuita. Usalo solo come pre-controllo.

Passo 2: controlla l’ordine

Verificare il preventivo dimostra che la promessa di prezzo è autentica. Non dimostra a quale ordine si riferisce il browser. Prima di memorizzare o evadere in base a un id d’ordine, recuperalo sul tuo server con GET /cfg/v1/orders/{id} e la tua chiave segreta. Restituisce hash del piano, hash del preventivo, stato, valuta e i tre totali in unità minori, e nessun dato personale. Confrontali con ciò che hai verificato.

Passo 3: ricevi il webhook

Configura un webhook come descritto nella pagina sugli ordini. Il tuo ricevente:

  1. legge il corpo grezzo prima di analizzarlo;
  2. legge l’intestazione CutOptim-Signature, t=<unix seconds>,v1=<hex> (possono esserci due valori v1 mentre un segreto viene ruotato);
  3. ricalcola HMAC-SHA256(secret, "<t>.<raw body>"), confronta in tempo costante e rifiuta un timestamp distante più di circa cinque minuti;
  4. rivendica l’id evento da CutOptim-Event-Id prima di eseguire qualsiasi operazione e ignora un id già gestito;
  5. ignora i tipi di evento che non conosce e risponde 2xx, così il mittente non ritenta inutilmente.

Ottieni il segreto del ricevente con POST /cfg/v1/admin/webhooks/{id}/secret e la tua chiave segreta. Tieni i segreti nel tuo ambiente, mai in una pagina, in un repository o in un log.

Codice di riferimento

Due piccoli esempi senza dipendenze mostrano tutti e tre i passi. Sono codice da leggere e copiare, non un servizio ospitato:

I loro segreti sono segnaposto. L’archivio dei duplicati in memoria presente negli esempi è un ripiego: in produzione, conserva gli id evento gestiti nel tuo database e rivendica un id nella stessa transazione che registra l’ordine.

Gli stessi passi, con le richieste e le risposte esatte, sono nel riferimento: Negozio personalizzato o ERP.

Rotazione delle chiavi

Una chiave o un segreto di webhook può essere ruotato con una sovrapposizione, in modo che il vecchio continui a funzionare per un tempo stabilito mentre distribuisci il nuovo. Durante la rotazione di un webhook una consegna porta due firme v1 per sette giorni, e accettarne una qualsiasi permette di passare senza interruzioni. I pulsanti della console per la rotazione con sovrapposizione non sono ancora realizzati; la console può creare e revocare le chiavi.

Altri modi per ricevere gli ordini

Per WooCommerce usa il plug-in. Se ti servono solo piani di taglio all’interno del tuo software, senza una schermata cliente integrata, si tratta dell’Engine API.

FAQ

Mi serve un plug-in per usare il configuratore con il mio negozio?
No. Il configuratore si integra con uno script e un elemento, e il tuo server fa tre cose: verifica il preventivo prima del carrello, controlla l'ordine a cui appartiene e verifica il webhook firmato. Questa pagina le descrive e rimanda al codice di riferimento in Node e PHP. WooCommerce ha un plug-in già pronto; nessun'altra piattaforma lo ha.
Come controlla un prezzo il mio server?
Invia il token del preventivo a POST /cfg/v1/quote/verify sul servizio del configuratore con la tua chiave segreta. La risposta indica se è valido o no e se è già stato riscattato. Poi confronta le claim del token con la propria riga di carrello: tenant, valuta, scadenza e hash del preventivo. Un controllo fatto solo in locale non può provare la firma, quindi non decidere mai un prezzo basandoti su di esso.
Verificare un preventivo lo consuma?
No. La verifica è in sola lettura. Solo l'invio dell'ordine consuma il preventivo, una volta. Un preventivo valido può risultare già riscattato, quindi controlla entrambi i campi.
Come so che un id d'ordine arrivato dal browser è l'ordine che ho verificato?
Cercalo sul tuo server: GET /cfg/v1/orders/{id} con la chiave segreta restituisce hash del piano, hash del preventivo, stato e totali di quell'ordine, mai dati personali. Confrontali con il preventivo verificato. Senza questo passaggio, un preventivo economico verificato potrebbe essere inviato insieme all'id di un ordine diverso.
Esistono un SDK o un documento OpenAPI?
Non c'è alcun SDK né un adattatore ospitato, ma esiste un riferimento API: ogni route, codice di errore e limite, con un documento OpenAPI 3.1 su /configurator/openapi.json che un generatore di client può leggere. I file di riferimento sono piccoli esempi senza dipendenze in Node e PHP, che puoi leggere e copiare. Python, Java e C# non sono coperti; la firma è un semplice HMAC-SHA256, quindi qualsiasi linguaggio può calcolarla.
Quali eventi del configuratore posso ricevere?
order.created e order.status_changed. Gli altri nomi di evento che la configurazione accetta, come gli eventi di preventivo o di progetto, non vengono mai inviati. La consegna avviene almeno una volta, quindi conserva un registro degli id evento che hai gestito.

Aggiornato: 19 ottobre 2026