API pubblica

L'API pubblica di Fullmetrix restituisce le tue metriche di vendita sotto forma di tabella, in formato JSON. Usala per alimentare uno strumento interno, un foglio di calcolo automatico, un data warehouse o una dashboard personalizzata. Il connettore Looker Studio si basa su di essa.

Un'API è un indirizzo web che un programma interroga al posto di un browser. Invii una richiesta che dice cosa vuoi, per esempio il fatturato giornaliero del mese scorso, e Fullmetrix risponde con i dati.

L'API è in sola lettura. Non può modificare nulla in Fullmetrix né nel tuo negozio.

Creare una chiave APICopy Anchor Link

Ogni richiesta deve portare una chiave API. La chiave identifica l'organizzazione di cui leggi i dati. Non c'è nient'altro da configurare.

L'elenco delle chiavi mostra per ognuna il Nome, il Prefisso, la data di creazione sotto Creato e Ultimo usato. Quest'ultima colonna ti aiuta a individuare una chiave che nessuno usa più. Per disattivare una chiave, clicca su Revocare, poi conferma. Qualsiasi integrazione che la usa smette subito di funzionare. Questa schermata è trattata in dettaglio in Chiavi API.

Crea una chiave per ogni strumento. Se devi disattivarne una, le altre continuano a funzionare.

AutenticarsiCopy Anchor Link

L'indirizzo di base dell'API è https://app.fullmetrix.com. Ogni richiesta porta la chiave nell'intestazione Authorization, dopo la parola Bearer.

curl https://app.fullmetrix.com/api/reports/catalog \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Le chiavi funzionano durante la prova gratuita e durante l'abbonamento. Se l'abbonamento dell'organizzazione si interrompe, le richieste vengono rifiutate finché non riprende.

Elencare i campi disponibiliCopy Anchor Link

GET /api/reports/catalog restituisce le dimensioni e le metriche che puoi richiedere. Una dimensione è un modo per suddividere i dati, come la data o il paese. Una metrica è un valore calcolato, come il numero di ordini.

curl https://app.fullmetrix.com/api/reports/catalog \
  -H "Authorization: Bearer fmx_YOUR_KEY"

{
  "dimensions": [
    { "id": "date", "label": "Date", "type": "date" },
    { "id": "store", "label": "Boutique", "type": "string" },
    { "id": "country", "label": "Pays", "type": "string" },
    { "id": "customer_type", "label": "Type client", "type": "string" },
    { "id": "status", "label": "Statut commande", "type": "string" }
  ],
  "metrics": [
    { "id": "orders", "label": "Commandes", "type": "number" },
    { "id": "items_sold", "label": "Produits vendus", "type": "number" },
    { "id": "gross_sales", "label": "CA brut", "type": "currency" },
    { "id": "net_revenue", "label": "CA net", "type": "currency" },
    { "id": "average_order_value", "label": "Panier moyen", "type": "currency" },
    { "id": "taxes", "label": "Taxes", "type": "currency" },
    { "id": "shipping", "label": "Livraison", "type": "currency" },
    { "id": "unique_customers", "label": "Clients uniques", "type": "number" },
    { "id": "new_customers", "label": "Nouveaux clients", "type": "number" },
    { "id": "returning_customers", "label": "Clients récurrents", "type": "number" }
  ]
}

I valori label vengono restituiti in francese. Usa i valori id nelle tue richieste.

Questa chiamata serve anche a verificare che una chiave funzioni. Risponde con lo stato 200 quando la chiave è valida.

DimensioniCopy Anchor Link

MetricheCopy Anchor Link

Gli importi sono nella valuta dei tuoi negozi e arrotondati a due decimali. I dati seguono le tue Impostazioni dei report, compresi gli stati esclusi e le deduzioni sulle vendite nette.

Interrogare le tue metricheCopy Anchor Link

GET /api/reports/tabular restituisce una tabella di righe. Ogni riga combina le dimensioni richieste con le metriche calcolate per quella combinazione.

ParametriCopy Anchor Link

Il periodo richiesto può coprire fino a due anni. Oltre, l'API lo accorcia mantenendo la data di fine, e la risposta mostra in from e to le date effettivamente usate.

Le date from e to sono lette in tempo universale, da mezzanotte a mezzanotte UTC. Il parametro timezone cambia solo il giorno mostrato per ogni ordine. Intorno a mezzanotte, alcuni ordini possono quindi finire a un giorno di distanza rispetto ai tuoi report Fullmetrix.

Esempio, fatturato per giornoCopy Anchor Link

curl "https://app.fullmetrix.com/api/reports/tabular?dimensions=date&metrics=orders,net_revenue&from=2026-09-01&to=2026-09-30&timezone=Europe/Paris" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

{
  "dimensions": ["date"],
  "metrics": ["orders", "net_revenue"],
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Paris",
  "rows": [
    { "date": "2026-09-01", "orders": 42, "net_revenue": 2318.4 },
    { "date": "2026-09-02", "orders": 37, "net_revenue": 1975.1 }
  ],
  "rowCount": 30
}

Le righe sono ordinate secondo l'ordine delle dimensioni richieste. rowCount indica il numero di righe restituite.

Esempio, vendite per paese e tipo di clienteCopy Anchor Link

curl "https://app.fullmetrix.com/api/reports/tabular?dimensions=country,customer_type&metrics=orders,net_revenue,average_order_value&from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Esempio, totali di un periodoCopy Anchor Link

Senza dimensione, la risposta contiene una sola riga.

curl "https://app.fullmetrix.com/api/reports/tabular?metrics=orders,gross_sales,net_revenue,new_customers&from=2026-01-01&to=2026-09-30" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Esempio, confrontare i tuoi negoziCopy Anchor Link

curl "https://app.fullmetrix.com/api/reports/tabular?dimensions=store&metrics=orders,net_revenue&from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Codici di risposta ed erroriCopy Anchor Link

Gli errori restituiscono un oggetto JSON con un campo error che descrive il problema.

Esempio di risposta 400 per una metrica sconosciuta.

{
  "error": "Dimensions ou métriques inconnues",
  "unknownDimensions": [],
  "unknownMetrics": ["revenue"]
}

Con un codice 429, la risposta porta anche le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Distanzia le tue chiamate e conserva i risultati che non cambiano, come i giorni passati.

Una risposta riuscita può essere servita da una cache per un minuto. Due chiamate identiche ravvicinate restituiscono quindi lo stesso risultato.

L'API accetta chiamate provenienti da un browser, ma ricorda che la chiave non deve mai essere esposta in una pagina pubblica.

Domande frequentiCopy Anchor Link