Documentazione tecnica per sviluppatori. Collega BaseLinker, WooCommerce, Apilo o la tua soluzione WMS/ERP proprietaria direttamente a Scopio Marketplace. Garantisci il recupero automatico degli ordini e la sincronizzazione dello stato delle spedizioni.
Chiavi API Venditore
Ogni richiesta alle API Scopio deve essere autorizzata con un token venditore unico. Questo token viene generato nel pannello di amministrazione. Utilizza l'intestazione Authorization con il prefisso Bearer, oppure direttamente l'intestazione X-API-Key.
I token contengono autorizzazioni collegate al tuo account venditore. Conservali in modo sicuro (ad esempio in variabili d'ambiente) e non esporli mai nel codice lato client. L'API richiede rigorosamente connessioni crittografate TLS 1.3.
# Authorization Header
Authorization: Bearer sk_mkt_ca1d5b9...
X-API-Key: sk_mkt_ca1d5b9...
Endpoint: GET /api/seller/orders
L'endpoint consente il recupero automatico degli ordini appena pagati. Restituisce solo gli articoli dell'ordine appartenenti alla tua offerta (filtrati per sellerId). L'indirizzo di spedizione e la modalità di consegna sono forniti in JSON.
L'intervallo di polling consigliato è tra 5 e 15 minuti. La risposta contiene il campo shipping_address con i recapiti completi dell'acquirente, la lista dei prodotti ordinati con codici EAN, quantità e prezzi.
# Response excerpt
{ "success": true, "orders": [...] }
Endpoint: POST /api/seller/orders/{orderId}/fulfill
Dopo aver imballato la spedizione e generato l'etichetta nel tuo ERP, invia lo stato di fulfillment a Scopio. Fornisci il numero di tracciamento e il corriere per aggiornare immediatamente l'ordine.
Codici corrieri accettati: inpost_locker (punti di ritiro), inpost_courier, dpd, dhl, ups. È anche possibile inviare un link PDF diretto per l'etichetta (label_url) per la visualizzazione all'interno di Scopio.
# Payload data
{ "tracking_number": "XYZ123", "carrier": "inpost_locker" }
Eventi HTTP POST istantanei
Configura un URL di Webhook nel tuo account venditore per ricevere notifiche in tempo reale. Il sistema invia una richiesta POST al tuo indirizzo non appena il pagamento dell'ordine viene confermato, eliminando il polling continuo.
Ciascun payload di webhook contiene un'intestazione di firma calcolata con un Webhook Secret per convalidare l'autenticità. In caso di errore, l'invio verrà tentato nuovamente 3 volte.
Pronto per l'economia degli agenti AI
Tutte le strutture degli ordini e degli stati sono pienamente compatibili con lo standard Universal Commerce Protocol (UCP). Ciò consente ai bot autonomi di ricerca e acquisto di analizzare facilmente i dettagli dell'ordine.
Grazie al formato UCP, le transazioni avviate da assistenti d'acquisto automatizzati vengono integrate nel tuo CRM senza la necessità di scrivere parser personalizzati per ogni singolo bot.
Sicurezza e stabilità dell'infrastruttura
Il limite di richieste predefinito è di 120 chiamate al minuto per chiave API o indirizzo IP. Qualsiasi superamento restituisce un errore HTTP 429. Le risposte di errore contengono un JSON strutturato con relativo codice.
Codici HTTP restituiti: 400 (payload errato), 401 (non autorizzato), 403 (accesso negato), 404 (ordine non trovato), 500 (errore interno del server). Tutti gli errori vengono registrati nei log.
# HTTP 429 Rate Limit Response
{ "error": "Too Many Requests", "retry_after_seconds": 60 }
