Per programmi e assistenti

L'API del registro

Formato holdmark-expediente/1.0 · versione v1

Tutto ciò che holdmark pubblica su un negozio si può leggere da un programma: senza chiavi, senza registrazione e gratis. Sono le stesse informazioni che chiunque vede sulla pagina di quel negozio, in un formato pensato perché lo capisca una macchina.

Come si usa

Una richiesta, un negozio, tramite il suo dominio:

curl https://holdmark.org/api/v1/tiendas/tienda-ejemplo.com

Il dominio può essere indicato con www. o senza, in maiuscolo o minuscolo: la risposta è la stessa. Per sapere cosa è disponibile e come si chiama ogni cosa, l'API si descrive da sé:

curl https://holdmark.org/api/v1

Cosa restituisce

Il fascicolo completo del negozio. Ogni fatto riporta la sua risposta, la sua fonte e il periodo a cui si riferisce:

{
  "format": "holdmark-expediente/1.0",
  "merchant": { "domain": "tienda-ejemplo.com", "platform": "shopify" },
  "facts": {
    "delivers_orders": { "answer": "yes", "value": 0.99, "source": "carrier" },
    "refunds_money":   { "answer": "yes", "source": "payment_processor" },
    "bank_claims":     { "value": 2, "unit": "per_1000_orders" },
    "verified_orders": { "band": "+50.000" }
  },
  "not_measured": ["customer_service", "product_quality", "opinions"],
  "rounding": "against the merchant"
}

Come leggere i numeri

• L'arrotondamento va sempre a sfavore del negozio: il favorevole per difetto e lo sfavorevole per eccesso. Un negozio non appare mai migliore di quello che è.
• Volume a fasce: mai il numero esatto di ordini, solo la fascia («oltre 50.000»).
• Ogni numero con il suo periodo: le contestazioni bancarie guardano ordini fino a dodici mesi; i rimborsi, una finestra più breve. È indicato su ogni fatto.
• Ciò che non si misura viene dichiarato: assistenza clienti, qualità dei prodotti e opinioni restano fuori, e il campo not_measured lo dichiara.
• Senza dati non si afferma nulla: se un negozio non ha dati sufficienti, il fatto risponde not_measured con la sua motivazione, non «no».

Limiti ed errori

• Fino a 120 richieste al minuto dallo stesso indirizzo. Superato quel limite, 429.
• 404 con tienda_no_registrada se quel negozio non è nel registro.
• 400 con dominio_no_valido se ciò che si richiede non è un dominio.
• Si può chiamare dal browser: l'API consente qualsiasi origine.
• Le risposte possono essere messe in cache per cinque minuti. I dati vengono ricalcolati una volta al giorno.

Quello che l'API non fa

Non esiste un elenco dei negozi né un modo per sapere quanti siano: si consultano uno alla volta, per dominio. È voluto, per proteggere le informazioni commerciali dei negozi registrati.

Non c'è nemmeno scrittura: nessuno può modificare un fascicolo dall'esterno, neanche pagando. I fatti derivano da ciò che registrano il corriere e il gestore dei pagamenti.

Condizioni d'uso

Puoi usare e citare questi dati indicando la fonte, holdmark.org, e collegandoti al fascicolo del negozio. Quello che non puoi fare è presentarli come qualcosa di diverso da ciò che sono: sono fatti misurati in un periodo, non una raccomandazione né una garanzia su un acquisto specifico.

Se costruisci qualcosa con questi dati e ti serve più volume di quanto consenta il limite, scrivici a equipo@holdmark.org.