Structora
Structora
Modalità Preventivi

Stai utilizzando Structora in modalità Preventivi

In questa modalità gli acquisti non vengono effettuati direttamente online. Puoi inviare richieste di preventivo ai rivenditori, che gestiranno direttamente prezzi, pagamento, consegna e assistenza.

API & Webhooks

Integra Structora
nel tuo gestionale.

REST API JSON + webhook firmati HMAC per sincronizzare prodotti, stock e ordini in tempo reale tra Structora e il tuo ERP, CRM o e-commerce. Nessun limite di chiamate per i partner attivi.

Inizia in 5 minuti Swagger / OpenAPI
Latenza
<150ms
Firma webhook
HMAC-SHA256
Auth
Bearer API key
Retry
5× con backoff
Step 1

Autenticazione

Genera una API key dal pannello Structora. Si mostra una sola volta — salvala subito in modo sicuro.

1
Crea la chiave
Vai su Account → API Keys, clicca "Genera chiave", dai un nome (es. "Mexal sync notturna").
2
Salva il valore
La chiave nel formato sk_str_xxxxxxxxxxxxxxxx compare una sola volta. Conservala in un password manager o variabile d'ambiente.
3
Usa nell'header Authorization
Tutte le chiamate autenticate richiedono l'header Authorization: Bearer sk_str_...
bash
# Esempio: ottieni i tuoi prodotti
curl -H "Authorization: Bearer sk_str_xxxxxxxxxxxxxxxx" \
     "https://api.structora.it/api/reseller/products"
Step 2

Endpoint REST

Tutto JSON. Date in ISO 8601. Importi in EUR con 2 decimali. Errori in formato RFC 7807.

Prodotti
CRUD completo del tuo catalogo
Ordini
Lettura ordini ricevuti + avanzamento stati
Preventivi
Gestione richieste preventivo da clienti
GET/api/productsPubblico

Catalogo pubblico con filtri (categoria, prezzo, marca, provincia).

curl
curl "https://api.structora.it/api/products?category=materiali&limit=20"
POST/api/products API key

Crea un nuovo prodotto nel proprio catalogo (richiede ruolo reseller).

curl
curl -X POST "https://api.structora.it/api/products" \
  -H "Authorization: Bearer sk_str_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cemento Portland 32.5R sacco 25kg",
    "description": "Cemento per usi strutturali.",
    "price": 4.20,
    "category": "materiali",
    "brand": "Italcementi",
    "stock": 500,
    "unit": "sacco"
  }'
PATCH/api/products/{product_id} API key

Aggiorna prezzo, stock o disponibilità del proprio prodotto.

curl
curl -X PATCH "https://api.structora.it/api/products/prod_abc123" \
  -H "Authorization: Bearer sk_str_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"price": 4.50, "stock": 320}'
GET/api/reseller/orders API key

Lista degli ordini ricevuti, filtrabili per stato e cliente.

curl
curl "https://api.structora.it/api/reseller/orders?status=paid" \
  -H "Authorization: Bearer sk_str_xxxxxxxxxxxxxxxx"
PATCH/api/reseller/orders/{order_id}/status API key

Avanza lo stato di un ordine (confirmed → preparing → shipped → delivered).

curl
curl -X PATCH "https://api.structora.it/api/reseller/orders/ord_xxx/status" \
  -H "Authorization: Bearer sk_str_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "shipped", "tracking_number": "BRT123456", "courier": "BRT"}'
Step 3

Webhook firmati

Structora chiama il tuo endpoint HTTPS quando succede qualcosa. Ogni richiesta è firmata HMAC-SHA256 con un secret personale.

Eventi disponibili

  • order.paid
    Ordine pagato con successo dall'acquirente.
    Per: rivenditore
  • order.shipped
    Ordine spedito (sincronizza con i tuoi corrieri).
    Per: rivenditore
  • order.delivered
    Ordine consegnato al cliente.
    Per: rivenditore
  • order.cancelled
    Ordine annullato.
    Per: rivenditore
  • order.refunded
    Rimborso emesso via Stripe.
    Per: rivenditore
  • quote.received
    Nuova richiesta di preventivo dal cliente.
    Per: impresa
  • quote.responded
    Risposta a preventivo inviata.
    Per: impresa
Configura webhook nel tuo pannello

Verifica firma HMAC

Ogni POST in arrivo include l'header X-Structora-Signature. Calcola HMAC-SHA256 del body usando il tuo whsec_ e confronta.

python
import hmac, hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In FastAPI / Flask:
sig = request.headers["X-Structora-Signature"]
if not verify_signature(request.body, sig, "whsec_xxxxxxxx"):
    abort(401)
event = request.json
# event = {"event": "order.paid", "order_id": "...", "at": "..."}
Riferimenti

Errori e limiti

Codici di errore
  • 400 Validazione
  • 401 Chiave invalida/revocata
  • 403 Permessi insufficienti
  • 404 Risorsa inesistente
  • 429 Rate limit superato
  • 5xx Errore lato Structora
Rate limit

Default: 600 richieste/minuto per API key. Upgrade automatico per partner con volume elevato — scrivi adev@structora.it.

Webhook retry

Se il tuo endpoint risponde con codice ≥500 o timeout (10s), Structora ritenta 5 volte con backoff esponenziale (1m, 5m, 30m, 2h, 6h). Dopo l'ultimo tentativo il webhook viene marcato failed.

Pronto a collegare il tuo gestionale?

Domande tecniche o richiesta di integrazione custom? Scrivici a dev@structora.it.

Genera la tua API keyContatta supporto sviluppatori