Interfaccia REST

Verificatoverificato 2026-09-20

In breve

L’interfaccia REST si trova su /api/v1 e risponde solo a GET. Qualsiasi altra cosa riceve 405 prima che il server guardi la chiave.

L’accesso si dimostra con un’intestazione: vedere la Panoramica.

Chiamate

Endpoint	Ambito	Cosa restituisce
`GET /account/connection`	`stores:read`	Diagnostica di questa connessione: l’app, chi ha concesso l’accesso e quando, permessi concessi e mancanti per area, e-shop e la modalità di scrittura tramite AI.
`GET /account/entitlements`	`account:read`	Il piano del cliente, le funzioni e i limiti con l’utilizzo attuale.
`GET /affiliate/articles/:key`	`affiliate:read`	Un articolo di aiuto con il testo (HTML) in tutte le lingue o in una sola; variabili non sostituite.
`GET /affiliate/articles`	`affiliate:read`	Gli articoli di aiuto del portale partner: chiave, predefinito/personalizzato, attivazione, ordine, stato per lingua (titolo, indirizzo, compilato, identico al predefinito).
`GET /affiliate/campaigns/:campaignId`	`affiliate:read`	Una campagna del programma partner.
`GET /affiliate/campaigns`	`affiliate:read`	Le campagne del programma partner dell’e-shop con ricompensa, disponibilità e conteggi.
`GET /affiliate/code-requests`	`affiliate:read`	Le richieste dei partner per un codice sconto proprio con stato e motivo; prima quelle in attesa.
`GET /affiliate/conversions/:conversionId`	`affiliate:read`	Il dettaglio di una conversione: importi, provvigione, stato della provvigione con motivo, stato dell’ordine nell’e-shop, nota di credito, pagamento.
`GET /affiliate/conversions`	`affiliate:read`	Le conversioni del programma partner dell’e-shop: base della provvigione e ordine completo IVA inclusa, provvigione, stato della provvigione con motivo, stato dell’ordine nell’e-shop, legame con il pagamento.
`GET /affiliate/discount-codes`	`affiliate:read`	I codici sconto dei partner sull’e-shop con numero di utilizzi e fatturato.
`GET /affiliate/documents/:key/content`	`affiliate:read`	Un documento legale del programma con il testo per lingua (testo salvato, testo pubblico, versione, impronte, fonte, metadati PDF) e le bozze aperte.
`GET /affiliate/documents`	`affiliate:read`	I documenti del programma (condizioni, accordi): politica di conferma, copia firmata, allegato e-mail, versioni per lingua, completezza e numero di conferme.
`GET /affiliate/email-templates`	`affiliate:read`	I modelli di e-mail ai partner per lingua (oggetto, attivazione, con l’evento anche il corpo) e gli allegati automatici dell’e-mail Account approvato.
`GET /affiliate/links/generate`	`affiliate:read`	Un link partner tracciato alla home, a un prodotto o a una categoria dell’e-shop della campagna; dopo il clic mantiene l’attribuzione al partner.
`GET /affiliate/partners/:partnerId`	`affiliate:read`	Un partner del programma con le campagne a sua disposizione.
`GET /affiliate/partners`	`affiliate:read`	I partner del programma con stato, rendimento e provvigioni; il contatto solo con i dati personali.
`GET /affiliate/payouts`	`affiliate:read`	I pagamenti delle provvigioni ai partner con lo stato; senza dati bancari e di fatturazione.
`GET /affiliate/portal`	`affiliate:read`	Il portale pubblico del partner: indirizzi per e-shop, apertura della registrazione con motivo, domini propri, persona di contatto, aspetto e stato dei testi per lingua.
`GET /affiliate/settings`	`affiliate:read`	Le impostazioni del programma partner: provvigioni, clic, pagamento minimo, segnalazione.
`GET /affiliate/signatures/:signatureId`	`affiliate:read`	Una firma elettronica con il testo firmato e l’istantanea dei valori; record immutabile, il PDF viene composto nell’applicazione.
`GET /affiliate/signatures`	`affiliate:read`	I documenti firmati elettronicamente dai partner (chi, documento, versione, lingua, e-shop, ora, modalità, verifica, impronte, stato) e i partner a cui manca la firma; solo lettura: la firma nasce esclusivamente nel portale.
`GET /affiliate/statistics`	`affiliate:read`	Le statistiche del programma partner: andamento per giorno, fonti di attribuzione, classifica dei partner.
`GET /affiliate/summary`	`affiliate:read`	La panoramica del programma partner dell’e-shop per il periodo: clic, conversioni, provvigioni, partner.
`GET /affiliate/variables`	`affiliate:read`	Il registro delle variabili dei contenuti e delle e-mail del programma partner: nomi canonici, alias, tipo, superfici, esempio; controllo facoltativo del testo per variabili sconosciute.
`GET /analytics/advertising`	`reports:read`	Pubblicità: spesa, budget, ROAS, incidenza pubblicitaria, CPA, valore medio dell’ordine e MER con confronto; Google Ads e Meta Ads, clic da GA4, 6 mesi.
`GET /analytics/channels`	`analytics:read`	La ripartizione di visite, ordini e fatturato per canale di marketing.
`GET /analytics/comparison`	`reports:read`	Fatturato a confronto: fatturato, ordini, AOV, visite, CR e AI/LLM rispetto al periodo precedente o all’anno prima.
`GET /analytics/monthly`	`reports:read`	Fatturato, ordini e visite per mese (al massimo 24), ad esempio anno su anno.
`GET /analytics/order-coverage`	`analytics:read`	La copertura degli ordini e del fatturato da parte della misurazione in analytics.
`GET /analytics/order-heatmap`	`reports:read`	Quando arrivano gli ordini: giorno della settimana × ora, giorno e ora più forti.
`GET /analytics/overview`	`analytics:read`	Visite, ordini, fatturato, tasso di conversione e quota AI/LLM per il periodo.
`GET /analytics/revenue-sources`	`reports:read`	Da dove arriva il fatturato: canali, totali AI/LLM, MitoOps e Affiliate, acquisizione secondo GA4.
`GET /analytics/seo`	`analytics:read`	Search Console: clic, impressioni, CTR e posizione per query o pagine.
`GET /automations/catalog`	`automations:read`	Il catalogo delle automazioni: trigger, condizioni, operatori, azioni, modelli; catalogVersion per le bozze.
`GET /automations/:workflowId`	`automations:read`	Un’automazione con il DSL e il risultato della validazione.
`GET /automations`	`automations:read`	Le automazioni del cliente con stato e ambito di e-shop.
`GET /automations/options`	`automations:read`	L’elenco dei valori per un campo di automazione (stati, spedizioni, pagamenti, modelli, reclami…): value per il DSL e nome.
`GET /automations/:workflowId/runs`	`automations:read`	La cronologia delle esecuzioni di un’automazione.
`GET /automations/templates`	`automations:read`	I modelli di automazione pronti con il DSL.
`GET /chatbot/conversations/:sessionId`	`chatbot-conversations:read`	La trascrizione di una conversazione con il chatbot web, con le fonti delle risposte del bot.
`GET /chatbot/conversations`	`chatbot-conversations:read`	Le conversazioni dei clienti con il chatbot web dalla più recentemente attiva, con la prima domanda; cursore.
`GET /chatbot/outcomes`	`chatbot:read`	How web chatbot conversations ended: since when the outcome is measured, measured and unmeasured conversations, known and unknown outcome, resolved, unresolved, bot error and resolution rate with its denominator; N/A with a reason when the denominator is zero. Totals only.
`GET /chatbot/stats`	`chatbot:read`	Le statistiche del chatbot web per il periodo: imbuto del messaggio, aperture, conversazioni, esiti, valutazioni.
`GET /chatbot/topics`	`chatbot:read`	Di cosa trattavano le conversazioni: quote degli argomenti, prodotti, tipo di pagina iniziale e candidati a lacune di conoscenza.
`GET /claims/config-drafts/:draftId`	`claims-settings:read`	Lo stato di una proposta di modifica delle impostazioni dei reclami (in attesa, scritta, rifiutata).
`GET /claims/configuration`	`claims-settings:read`	Le impostazioni dei reclami: etichette, campi, trasporto di reso, modulo sull’e-shop, tipi di modulo.
`GET /claims/:code`	`claims:read`	Un caso con articoli e collegamenti: ordine, nota di credito, spedizione di reso, movimento di magazzino.
`GET /claims`	`claims:read`	I reclami e i resi di un e-shop dal più recente.
`GET /claims/refund-options`	`claims-settings:read`	Refunds: variable symbol source, refund coupon validity, coupon in the form, when the form asks for an account number.
`GET /claims/:code/refund-readiness`	`claims:read`	Claim before a refund: what the customer requests, masked account, variable symbol, mode and whether the claim can be deleted.
`GET /claims/refund-settings`	`claims-settings:read`	Rimborsi dei reclami: modalità, conti bancari con idoneità all’ordine di pagamento (mascherati), conto predefinito e manuale.
`GET /claims/routes`	`claims-settings:read`	Spedizione di reso dei reclami: percorsi, indirizzi, profili dei corrieri con ID e supporto al reso, tipi di caso.
`GET /claims/settings`	`claims:read`	I processi dei reclami con ID e nomi (tipi, passaggi, stati, termini), etichette; le impostazioni del modulo con l’ambito claims-settings:read.
`GET /claims/statistics`	`claims:read`	Le statistiche di reclami e resi per il periodo: conteggi, tempi di gestione, tipi, valutazioni, motivi.
`GET /claims/templates`	`claims-settings:read`	I modelli di e-mail (oggetto, testo, quando e se vengono inviati automaticamente) e dei verbali dei reclami.
`GET /content/articles`	`products:read`	Gli articoli del blog dell’e-shop con l’indirizzo sul web e l’immagine di anteprima.
`GET /coupons/activation-link`	`coupons:read`	Un link che applica al cliente nel carrello un coupon ESISTENTE. Non crea il coupon.
`GET /coupons/activation-status`	`coupons:read`	Se il coupon si può usare sull’e-shop tramite il link di attivazione: mirror del coupon + stato del codice sul web.
`GET /coupons/capabilities`	`coupons:read`	Cosa sa fare con i coupon la piattaforma dell’e-shop. Leggetelo prima di crearne.
`GET /coupons/:code`	`coupons:read`	Un coupon dall’archivio di MitoOps. Quando non c’è, la risposta è “non trovato”.
`GET /coupons`	`coupons:read`	I coupon sconto dell’e-shop con tipo e valore dello sconto, validità e stato derivato.
`GET /customers/:customerKey`	`customers:read`	Un cliente della rubrica: identità, e-shop, importi LIFETIME e facoltativamente PERIOD, ripartizione per e-shop.
`GET /customers`	`customers:read`	La rubrica clienti: identità (con mascheramento dei dati personali), e-shop, lingua, conteggi LIFETIME e fatturato per valuta; filtro facoltativo dell’attività di acquisto nel periodo.
`GET /customers/performance`	`reports:read`	I clienti come pseudonimi: numero di ordini, fatturato, primo e ultimo ordine, acquisto ripetuto, LTV.
`GET /credit-notes`	`invoices:read`	Ricerca nelle note di credito.
`GET /documents`	`invoices:read`	Documenti contabili di un tipo (fatture, fatture proforma, note di credito) per pagine con ciclo di vita, stato nella fonte, filtro di validità e disponibilità del PDF.
`GET /documents/:documentType/:code/pdf`	`invoices:read`	PDF di una fattura, fattura di acconto o nota di credito (base64 e SHA-256), gli stessi byte mostrati a schermo.
`GET /invoices/:invoiceCode`	`invoices:read`	Una fattura con righe, importi, note di credito e fatture di acconto collegate.
`GET /invoices`	`invoices:read`	Ricerca nelle fatture.
`GET /inventory/movements`	`inventory:read`	La cronologia dei movimenti di magazzino: quando, cosa, di quanto, perché e da quale fonte.
`GET /inventory/availability`	`inventory:read`	La giacenza di più articoli contemporaneamente.
`GET /inventory/stock`	`inventory:read`	La giacenza di un articolo con la fonte del valore.
`GET /orders/:orderCode`	`orders:read`	Un ordine salvato, righe comprese.
`GET /orders`	`orders:read`	Gli ordini salvati di un e-shop, dal più recente.
`GET /availabilities/drafts/:draftId`	`products:read`	Lo stato di una proposta di modifica del catalogo delle disponibilità: in attesa di approvazione, scritta con risultato, rifiutata, scaduta.
`GET /availabilities`	`products:read`	Il catalogo delle disponibilità dell’e-shop: nome, descrizione, rifornimento, consegna, significato per Google, colore, ruolo predefinito.
`GET /catalog/category-content-drafts/:draftId`	`category-content:read`	Stato di una proposta di testi delle categorie: in attesa di approvazione, scritta, rifiutata, scaduta.
`GET /categories/:guid/content`	`category-content:read`	Testi di una categoria (descrizione superiore e inferiore, titolo e descrizione SEO) con impronta e scrivibilità.
`GET /categories`	`products:read`	Le categorie dell’e-shop con il numero di prodotti.
`GET /catalog/product-content-drafts/:draftId`	`product-content:read`	Stato di una proposta di testi dei prodotti: in attesa di approvazione, scritta con avvisi dell’e-shop, rifiutata, scaduta.
`GET /products/:code/content`	`product-content:read`	Testi di un prodotto dall’e-shop (descrizione, descrizione breve, titolo e descrizione SEO) con impronta e scrivibilità.
`GET /product-content/policy`	`product-content:read`	Criteri dei contenuti dell’e-shop senza chiamare l’e-shop: cosa può leggere e proporre questo accesso, quali campi scrive la piattaforma, modalità di approvazione e scrittura autonoma, limiti e impronte.
`GET /products/:code`	`products:read`	Un prodotto per codice, con classificazione e prezzo dalla scheda.
`GET /products`	`products:read`	Ricerca dei prodotti per nome, codice, EAN o PLU.
`GET /reports/financial-summary`	`reports:read`	Il riepilogo finanziario del periodo: fatturato, IVA, ordini, AOV; con i diritti anche acquisto, utile lordo, costi e risultato.
`GET /sales/order-performance`	`reports:read`	Il fatturato per ordine in EUR con i totali per l’intero periodo; con il diritto anche acquisto, utile lordo e margine per ordine.
`GET /sales/product-performance`	`reports:read`	Le vendite per prodotto dai documenti; con il diritto anche il prezzo di acquisto al momento della vendita e il margine.
`GET /search-console/query`	`search-console:read`	Search Console per giorno, query, pagina, paese e dispositivo, con paginazione e hash del contenuto.
`GET /search-console/status`	`search-console:read`	Stato di Search Console del negozio: connessione, proprietà, autorizzazione, sincronizzazione e ampiezza dell’archivio.
`GET /shipping/carriers`	`shipping:read`	I corrieri collegati e i loro profili, senza dati di accesso.
`GET /shipping/shipments/:shipmentId`	`shipping:read`	Una spedizione con tutti gli eventi di tracciamento.
`GET /shipping/shipments`	`shipping:read`	Le spedizioni di un e-shop con corriere, paese e orari di affidamento e consegna.
`GET /shipping/stats`	`shipping:read`	Le statistiche di consegna per corriere: conteggi, tasso di successo, mediana e p90 del tempo di consegna, paesi.
`GET /stores/integration-status`	`stores:read`	Lo stato del codice MitoOps sul web per e-shop: installato, versione, moduli, predisposizione del coupon dall’indirizzo.
`GET /stores`	`stores:read`	L’elenco degli e-shop del cliente con il loro codice.
`GET /suppliers/:supplierId`	`purchasing:read`	Un fornitore con le offerte di prodotti e le componenti di costo.
`GET /suppliers`	`purchasing:read`	I fornitori del cliente con il numero di offerte e di prodotti abbinati.
`GET /webhooks/endpoints/:endpointId/deliveries`	`webhooks:read`	Il registro delle consegne di un endpoint, senza corpo.
`GET /webhooks/endpoints/:endpointId`	`webhooks:read`	Un endpoint webhook con il numero di consegne in attesa.
`GET /webhooks/endpoints`	`webhooks:read`	Gli endpoint webhook del cliente senza segreti e lo stato della coda.
`GET /webhooks/events`	`webhooks:read`	Il catalogo degli eventi dei webhook in uscita, la busta e la firma.

Indirizzo	Ambito	Cosa restituisce
`GET /capabilities`	—	cosa può chiamare questa chiave
`GET /openapi.json`	—	descrizione dell’interfaccia leggibile dalle macchine

GET /capabilities è il modo più rapido per scoprire cosa apre una chiave: restituisce esattamente ciò che i suoi ambiti le consentono, non l’intero catalogo. I parametri esatti e i campi della risposta di ogni chiamata sono in openapi.json.

Forma della risposta

Ogni risposta ha due parti: data e meta.

{
  "data": [ { "market": "sk", "name": "Il mio e-shop" } ],
  "meta": { "requestId": "…", "count": 1 }
}

meta.requestId è l’identificatore della chiamata. Se qualcosa va storto, è il dato che dice all’assistenza di quale chiamata si trattava.

Negli elenchi meta contiene inoltre:

Campo	Significato
`count`	quanti record ci sono in questa risposta
`hasMore`	`true` quando esiste una pagina successiva
`nextCursor`	il valore con cui chiedete la pagina successiva; `null` quando non ce n’è

Nei riepiloghi (statistiche, panoramica, riepilogo finanziario) l’intera risposta è in data come un unico oggetto.

Paginazione

La pagina successiva la chiedete rimandando il nextCursor della risposta nel parametro cursor:

curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&limit=50&cursor=<nextCursor>"

Tre cose su cui si basa:

Gli altri parametri devono restare uguali. Il cursore appartiene alla query con cui è nato. Con un e-shop, un periodo o un filtro diversi l’interfaccia lo rifiuta (400): proseguire in un ordine che non vale più restituirebbe in silenzio una porzione incoerente.
La fine si riconosce da hasMore, non dal numero. Una risposta può avere esattamente tanti record quanti ne avete chiesti e la pagina successiva esistere comunque.
Un cursore non valido è un errore, non un risultato vuoto. Una risposta vuota sembrerebbe la fine dei dati e un’esportazione si accorcerebbe in silenzio.

Con il cursore si paginano ordini, documenti, catalogo e spedizioni. La numerazione delle pagine l’interfaccia di proposito non ce l’ha: quando tra due chiamate si aggiunge un record, “pagina 2” punta altrove rispetto a un attimo prima; il cursore porta l’ultimo record visto, quindi nulla si ripete né si salta.

Elenco e ricerca

Per prodotti, fatture e note di credito si tratta di due modalità dello stesso indirizzo:

Come chiamate	Cosa ottenete
senza `query`	elenco per pagine, dal più recente; si può paginare e limitare per periodo
con `query`	ricerca ordinata per corrispondenza; restituisce al massimo `limit` record

La ricerca non si pagina e non si limita per periodo: l’ordine per corrispondenza cambia tra una chiamata e l’altra e un cursore su di esso salterebbe dei record. La combinazione di query con cursor, from o to termina quindi con 400, non con un filtro ignorato in silenzio.

Per leggere l’intero archivio usate l’elenco senza query.

Periodo

Ordini, documenti, spedizioni, statistiche, analytics e report si possono limitare con i parametri from e to nella forma YYYY-MM-DD.

Entrambi i limiti sono inclusi. to=2026-08-05 comprende tutto il 5 agosto, non la mezzanotte al suo inizio.
Il giorno si considera come lo registra l’applicazione: gli ordini nel fuso dell’e-shop, spedizioni e report come li vede il personale sullo schermo.
Gli ordini si ordinano per data di creazione dell’ordine, le spedizioni per data di creazione della spedizione.
Fatture e note di credito per data fiscale; quando il documento non la ha compilata, per data di emissione. Quale valore ha classificato il documento si vede nel campo businessDate.
Vendite per prodotto per data del documento; qui il periodo è obbligatorio.
Il periodo più lungo è di 366 giorni. Uno più lungo viene rifiutato; una cronologia più lunga percorretela anno per anno.
Un periodo invertito è un errore, non un risultato vuoto: altrimenti un refuso sembrerebbe un periodo senza documenti.
Senza periodo spedizioni e statistiche restituiscono gli ultimi 30 giorni, analytics e riepilogo finanziario il mese corrente. La risposta indica sempre il periodo.

Per gli ordini resta anche todayOnly. Non si può combinare con from/to: sono due risposte alla stessa domanda e una delle due vincerebbe in silenzio.

Cosa significano i campi finanziari

purchasePriceWithoutVat nella riga dell’ordine è il prezzo di acquisto al momento dell’ordine, come lo ha salvato l’e-shop. Non è il prezzo dalla scheda prodotto di oggi: quello è in products/{code} come purchasePrice.
cogs nel riepilogo finanziario è l’acquisto della merce per il periodo da tutti gli ordini; null significa che i prezzi di acquisto non sono noti per abbastanza righe (cogsCoverage). In quel caso non viene mostrato nemmeno l’utile lordo: meglio niente che un numero sbagliato.
grossProfit è il fatturato senza IVA meno l’acquisto della merce, grossMargin lo stesso in percentuale. resultAfterCosts è l’utile lordo meno la spedizione meno i costi aziendali: un numero gestionale, non l’utile contabile.
Nelle vendite per prodotto purchaseCostWithoutVat è il prezzo di acquisto al momento del documento secondo l’abbinamento con il catalogo; unmappedLines dice quante righe non sono state abbinate.
Tutti gli importi di report e analytics sono in EUR (campo currency), convertiti al cambio del momento della sincronizzazione. Ordini e documenti portano la propria valuta.

Senza l’ambito purchase-prices:read questi campi nella risposta non ci sono: non sono a zero, mancano.

Tempo di consegna

Le statistiche di consegna (shipping/stats) misurano il tempo dall’affidamento al corriere al primo evento di consegna tra gli eventi di tracciamento. Dalla data dell’ordine non si calcola nulla. Una spedizione che non ha entrambi i punti non rientra nella mediana; quante ne sono state conteggiate lo dice delivery.measured. Gli stessi due orari li porta ogni spedizione nei campi handedOverAt e deliveredAt.

deliveryRate è la quota delle consegnate tra quelle il cui esito si è già concluso (consegnate, rese, errate). Una spedizione in transito non è ancora né un successo né un insuccesso; una spedizione annullata è un’azione vostra, non un fallimento del corriere, e non si conta affatto.

Giacenze

inventory/stock restituisce quantity e source: da quale modello di registrazione proviene il valore (varianti, bilancio dell’e-shop, scheda prodotto). Quando l’e-shop tiene il bilancio, sono disponibili anche physical, available (disponibile per la vendita) e reserved (riservato negli ordini); altrimenti sono null. L’interfaccia non inventa alcuno “stato a magazzino” che l’applicazione non registra.

La giacenza (inventory/stock e inventory/availability, ambito inventory:read) dice quanta merce c’è; il catalogo delle disponibilità (/availabilities, ambito products:read) sono gli stati con un nome che l’e-shop mostra al cliente accanto al prodotto, ad esempio Disponibile o Su ordinazione.

Catalogo delle disponibilità

GET /availabilities?market=sk restituisce in data le voci del catalogo di un e-shop: id, name, description, onStockHours, deliveryHours, meaning (significato per Google Shopping: in_stock, backorder, preorder, out_of_stock), color, system, defaultRoles (ruolo predefinito nell’e-shop) e pairingRows (in quante righe dell’associazione delle disponibilità si trova la voce). meta porta market, manageable e reason: se il catalogo si può modificare in MitoOps e, se no, perché (PLATFORMA, BEZ_ROZSIRENIA, PROSTREDIE).

La modifica del catalogo tramite REST non è possibile. Può prepararla solo un assistente tramite MCP, e come proposta con l’ambito sensibile availabilities:draft; nell’e-shop la scrive solo una persona approvandola nell’applicazione. Lo stato di una proposta del genere lo leggete tramite REST: GET /availabilities/drafts/:draftId restituisce status (pending, writing, executed, partial, failed, rejected, expired), l’anteprima e, dopo l’approvazione, il risultato per voce. Dettagli nell’interfaccia MCP.

Rubrica clienti

I clienti hanno due letture diverse e confonderle significa leggere un numero diverso da quello che vi aspettate:

/customers e /customers/{customerKey} (ambito customers:read) sono la rubrica: la stessa proiezione che il personale vede nella schermata Clienti e che va nell’esportazione: identità, e-shop, paese, lingua, conteggi e date.
/customers/performance (ambito reports:read) è l’analisi sugli ordini grezzi: il cliente è solo uno pseudonimo, nome e contatto non ci sono affatto.

Dall’esterno market è obbligatorio in entrambi. Senza di esso la lettura attraverserebbe tutti gli e-shop del cliente, anche quelli che non appartengono all’accesso.

Chi vede cosa

customers:read da solo fornisce lo pseudonimo (customerKey), gli e-shop, il paese, la lingua, il numero di ordini e le date del primo e dell’ultimo ordine. Inoltre:

nome, azienda, e-mail, telefono e genere di marketing solo con personal-data:read,
fatturato, ordine medio e LTV solo con reports:read.

I campi per cui non avete l’ambito vengono rimossi, non azzerati. null al posto dell’e-mail significherebbe “il cliente non ha e-mail”, il che non è vero: una chiave mancante significa “non ne avete il diritto”.

customerKey è lo SHA-256 dell’e-mail normalizzata. È lo stesso pseudonimo che portano i documenti (customerEmailHash) e /customers/performance, quindi le tre viste si possono unire senza inviare l’e-mail da nessuna parte.

Intero ciclo di vita e periodo

La rubrica ha un filtro facoltativo purchaseFrom e purchaseTo (YYYY-MM-DD, entrambi i limiti inclusi). Significa attività di acquisto nel periodo: il cliente ha almeno un ordine in quell’intervallo. Non è un filtro sulla data del primo o dell’ultimo acquisto.

Con il periodo si aggiungono i campi periodFrom, periodTo, periodOrdersCount e periodRevenueByCurrency accanto a quelli dell’intero ciclo di vita (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt), mai al loro posto. I valori dell’intero ciclo di vita non cambiano con il periodo.

Il denaro è sempre per valuta

Fatturato, ordine medio e LTV sono un array per valuta, mai un solo numero. Un cliente con ordini in EUR e in CZK ha due voci; sommarle in un unico scalare significherebbe aggiungere corone agli euro. Lo stesso vale per /customers/performance: una riga è una coppia (cliente, valuta) e i totali del filtro sono totals.revenueByCurrency.

Lingua e genere di marketing

language è la lingua dell’e-shop in cui il cliente ha ordinato (source: "store_locale"), non una sua scelta. L’applicazione oggi non registra una preferenza linguistica esplicita del cliente.
marketingGender (male / female / unknown) è una stima dal nome di battesimo, non un dato indicato dal cliente. L’origine è sempre in genderSource (oggi esclusivamente name_inference o unknown) e l’affidabilità in genderConfidence. Un cliente aziendale non ha il campo. Chi lo mostra altrove deve dire “stima in base al nome”, mai “indicato dal cliente”. Richiede personal-data:read come il nome stesso.

E-shop

Le chiamate sui dati di un singolo e-shop ne chiedono il codice nel parametro market. L’elenco dei codici lo fornisce GET /stores.

Quando la chiave non ha l’ambito per quell’e-shop, la risposta è 403, non un elenco vuoto. Un elenco vuoto non si potrebbe distinguere da un e-shop senza ordini. Un record di un altro e-shop (ad esempio una spedizione) è 404.

Errori

Una risposta di errore ha sempre la stessa forma e porta un codice. L’elenco degli stati e dei codici è nella Panoramica.

Esempi

# Ordini per un periodo, per pagine
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Statistiche di consegna di agosto
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Spedizioni di un corriere ad agosto
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&carrier=dhl"

# Riepilogo finanziario di agosto (con il diritto ai prezzi di acquisto anche l'utile lordo)
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/reports/financial-summary?market=sk&from=2026-08-01&to=2026-08-31"

# Giacenza di tre articoli
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/inventory/availability?market=sk&codes=A100,A101,A102"

# Catalogo delle disponibilità dell'e-shop
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/availabilities?market=sk"